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Advanced Mac ing 
Modifying Apple's SCSI Driver 


How to Make Apple's 'non-functional' SCSI Driver, 
Functional! 


Happy New Year and welcome to our fourth volume. We'll 
step right in the middle of things with a SCSI driver project that 
will take us two columns. 

You've seen several articles on SCSI device handling in 
MacTutor; Tim Standing's contributions in V3#2 and V3#6, and 
my own column in V3#3. We showed you how to hook up the 
electronics of a generic SCSI disk to the Mac, how to play with 
SCSIcommands and doraw data transfers, and how to format the 
SCSI disk. One crucial thing has always been missing: the SCSI 
driver itself. 

History 


It's been over a year now that I hooked up my own 80 MByte 
disk, a Quantum Q280, to my Mac (Plus at that time), and was 
confronted with all those problems, including getting a driver 
that would make my disk work. That last part turned out to be the 
hard one, at that time. 

All information that I could then get hold of was the source 
of a ‘generic’ SCSI driver published by Apple in a Software 
Supplement, and also available on various bulletin boards. The 
problem with this driver was that it wouldn't quite work as 
promised. In this column I'll explain the modifications that I had 
to do to the Apple driver to make it boot and run on the Quantum 
0280 disk. 1 am not claiming that it will drive any SCSI disk, 
although in theory it should drive many of them; in practice, 
however, a Seagate ST225N will run with the original code 
supplied by Apple, butnot with my code. However, by describing 
my implementation and its differences to the original, I hope to 
give you some hints what can be done to make an arbitrary SCSI 
disk work with a fully or partially home-brew driver. 

Some of you might find this information out of date, since by 
now the HD SC installer has been released by Apple. Alas: I lost 
a lot of time backing up some 63 Megabytes to run the HD SC 
installer on my Q280; only to find out that the drive wasn't 
recognized and I had to re-install my old driver. Which, as you'll 
see soon, is admittedly some kind of a kludge, but has performed 
without problems for over one year now. 

Itis for exactly thereason that, after all, SCSI devices are not 
that generic, that David Smith asked me to write about my SCSI 
driver [Apple Expo, Paris Sept 30: “You really have a SCUZZY 
driver? Well, publish it! "]. Therefore, not much Forth this month. 
Rather assembler, and general ramblings. Next month I'll con- 
tinue with a re-implementation of Apple's SCSI driver in ... 
Forth. Yes, that's right. Just to get all you assembly/ hardware 
guys out there to buy your copies of Mach2. 
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Apple’s ‘generic’ SCSI driver 


There are two problems with printing the full, commented 
source listing of Apple’s driver here (I already mentioned this in 
the March 87 article). First, although it is almost two years old, 
it is copyrighted by Apple. Second, the source is quite long, 
(some 12 pages with comments) and it is available through 
APDA, Delphi, Compuserve and who knows where. I think it is 
much simpler that you download a copy of the [heavily com- 
mented] driver's source - I got mine from Delphi - and follow the 
explanations in this article to understand what it's doing. The 
parts of the driver that I modified are printed in the listing. The 
complete source of a SCSI driver, written in Forth, will follow 
next month. 

[The SCSI driver example is a product of APDA, part % 
KMSSDP, which sells for $10. The APDA catalog says, and I 
quote: 'Contains a heavily commented, but non-functional, 
sample scsi driver written in Assembly language' . Jórg' s article 
should help make it functional! We сап t distribute it since APDA 
is selling it as a product, so please contact them for this source. 
You'll also want to make sure you have the 2.0b1 MPW Shell 
release, which contains the latest assembler equates including 
the SCSI equates. Included with the scsi example is a eight page 
handout which says: 'It is provided to shows how such a driver 
might be written (by someone with not a lot of time to tell 
developers how to write drivers!) . And again, this little gem: 
“Unfortunately, if you happen to have gotten a good deal on an 
old 370 meg drive that you want to hook up to your Macintosh, 
we can’ treally help you (there are only six of us for all Macintosh 
development, and four thousand of you!) . The comments go on 
to state that the Technical Support Group's charter is to help 
developer’ s in creating products for market, so I assume any 
subject that does not appear to lead to product development is 
given little developer support! I have always disagreed with this 
narrow view of software development. The amount of Macintosh 
software developed in-house far exceeds what little commercial 
"MS Word" type program development that is going on, and this 
will only increase as the Mac II moves into big-time engineering 
departments. Computers were tools for problem solving long 
before they were a means to help Apple sell more computers. -Ed] 


The structure of a SCSI driver 


Like any driver, the SCSIdriver will have a header before the 
actual driver code. This header looks like the following: 


[word] — $4F00 
;read, write, control, stetus, needs lock 


Flags 
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[word] $9 
[word] $0 
[word] $0 


jno periodic action 
¿no event mask 
;no menu 


; Entry point offset table 


[жога] offset to Open routine 
[word] offset to Prime routine 
[word] offset to Control routine 
[word] offset to Status routine 
[word] offset to Close routine 


[counted string] the driver name 


The block number at which the driver can be found on the 
disk, and its length, are given in the device descriptor map 
(DDM) on block 0 of the SCSI disk. On bootup, the driver is 
found (hopefully) at the location given in the DDM, read from the 
disk, anda jump is made to the beginning of the driver. Therefore, 
an SCSI driver must contain executable code before the header. 
Usually, a JMP or BRA instruction is contained here that jumps 
to a piece of code which does the actual initialization and 
installation. 

SCSI driver installation 


The procedure by which the Macintosh will installthe driver 
on bootup is partly described in IM IV-293, partly in the com- 
ments to Apple's SCSI driver source. I'll summarize the relevant 
information here. 

On bootup, the Macintosh will try to select a device on the 
SCSI bus by its ID, starting with ID=6 and going downward. In 
the older systems, the highest ID found was used as the number 
ofthe startup device; inthe new system releases, the control panel 
allows you to select where you want to boot from. 

The driver descriptor and device partition maps are then read 
from block 0 and 1 of the startup device. Their signatures are 
checked; the first word of block 0 must be $4552, and of block 1, 
$5453. The driver descriptor map (DDM) must contain an entry 
that corresponds to a driver for the Macintosh (processor type - 
l,asexplained in V3#3). The driver is read from the blocks given 
in the DDM and put into memory allocated in the system heap. 
Then the Macintosh jumps to the beginning of the driver code. 

The driver code is supposed to ‘install’ itself. In Apple's 
code, the installation routine is located at the very end of the 
driver. It takes three parameters on entry: 


- AO, a pointer to the device partition map 
- D5, the SCSI ID of the device for this driver 
- D7, default data start area', not used in the Apple driver. 


I'll explain the steps the installer goes through. First, we 
have to let the system know that we exist. The table of existing 
drivers is the unit table (IM II-191), apointer to whichis available 
through the system global UTableBase ($11C). The unit table 
contains a handle to the unit’s device control entry at 
UTableBase+unitnumber*4. By definition, the unit number of 
the SCSI device is its SCSI ID + 32. The driver reference number 
for a device is the two’s complement of its unit number. 

We therefore know our unit number and reference number 
when the installation routine is entered. The trap Drvrinstall 
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(Toolbox $A03D, and not documented in IM), called with the 
driver reference number in DO, will allocate a new device control 
entry for the driver and puta handleto this DCE into the unit table. 
The format of a DCE, as given in IM II-190, looks like: 


TYPE DCtlEntry = RECORD 
DCtlDriver : Ptr ; 
(ptr to ROM or handle to RAM driver) 
DCtlFlags : Integer ; (flags) 
DCtlQHdr : QHdr ; (driver's i/o queue) 
DCtlPosition : LongInt ; 
(byte pos used by read and write calls) 


DCtlStorege : Handle ; 
(hndl to RAM drivers private storage) 
DCtlRefNum : Integer ; 


(driver's reference number) 
DCtlCurTicks : LongInt ; 
(long counter for timing system task calls) 
DCtlWindow : Ptr ; 
(ptr to driver’s window if anu) 
DCtlDelay : Integer ; 
(number of ticks btwn sysTask calls) 
DCtlEMask : Integer ; 
(desk acessory event mesk) 
DCtlMenu : Integer ; 
(menu ID of menu associated with driver) 
END ; 


After the DCE has been created, some of its fields (DCt 1D- 
river, DCtlFlags, DCtlDelay, DCtlEmask, and 
DCtlMenu) are filled using the information in the driver 
header. The driver will be marked “ROM based" (bit 6 of 
dCtlFlags - 0), because the header contains a pointer to the 
driver. 

Next, the Open trap is called with the driver's name as its 
parameter. If the driver cannot be opened for some reason, 
DrvrRemove (Toolbox $A03E, also undocumented) is called 
with thereference number in DO, and the memory allocated to the 
driver is disposed with a call to DisposPtr. 

If the driver has been opened correctly, the device partition 
map is checked fora partition with the file system ID ‘TFS1’. The 
offset to this partition and its size are remembered in the local 
variables area of the driver. It is this partition which will be 
mounted as a Macintosh volume. 

Finally, if the install routine has been called at boot time, the 
dNeedTime flag is set in the DCtlFlags word; this way the driver 
gets called by the desk manager when the system comes up. This 
will allow us to post a disk-insert event for this volume at that 
time. The reason to do this is that on boot-up the system 
remembers only the drive that was actually used to boot from. 
Thus, in case the boot was made from another drive (such as a 
floppy), our SCSI drive will have to be re-mounted, even though 
the driver has already been installed. 


The Open routine 


The Open routine will get memory for the driver's local 
variables and add the SCSI drive to the drive queue. Entry 
parameters to this routine are, as for all five driver routines 
(Open, Control, Prime, Status, Close) a pointer to a parameter 
block in AO and to the device control entry in A1. 


First, a block is reserved in the system heap for the local 
variables and its pointer stored in the driver's DCE. The drive 
number is initially set to 5, and the drive queue is traversed, 
starting at its head (contained in the system global 
DrvQHdr*QHead = $30A), to see whether the drive number is 
already in use. If it is, it is incremented by 1 and the queue 
checked again until an unused drive number has been found. This 
drive number is stored in a local variable. The drive queue 
element (IM II-127) for our drive is also set up in the local 
variable space and some of its fields are preset (see TN36, which 
also describes a routine that adds a drive to the drive queue in a 
very similar way): 

The qType field is set to 1. This indicates that the drive size 
may be greater than 32 MBytes and that one more 16-bit word is 
following the dQDriveSize field of the drive queue element; this 
word indicates the high-order word of a 32-bit block count. With 
the old definition of the drive size (4Туре - 0), a 16-bit block 
count was used, allowing a maximum size of only 32 MBytes. 
We therefore have to remember that the high- and low-order 
words of the drive size are reversed when we are working with 
this variable later. The dgDrvSize is initialized to zero; this field 
will be filled by the Install routine after the driver is open. The 
dOFSID field is also set to 0 to indicate a normal HFS volume. 
The four bytes preceding the drive queue element contain flags 
(IM П-128); byte 1 of these flags is set to 8 to indicate a non- 
ejectable disk. The remaining flags are cleared. 

The drive is added to the drive queue using the AddDrive trap 
($A04E, not documented in IM) with DO containing the drive 
number in its high order word and the driver reference number in 
its low order word, and AO containing a pointer to the drive queue 
element. 

The last action of the Open routine is to set up an SCSI 
pseudo program for read/write transfers in the local variable 
space. We use a very simple one: 


SCNOINC 
SCSTOP 


buffer, "bytes 


and this is where we first deviate from the Apple driver. 
Apple's example uses (and this works with the ST225N): 


061 SCINC buffer, "bytes 
SCLOOP 61, count 


SCSTOP 


which will transfer count blocks of bytes each starting 
at address buf fer. Our driver, on the contrary, will transfer all 
bytes requested in one single chunk. The reason for this will be 
explained later. First, keep yourself content with the fact that one 
method works on the Q280 and the other on the ST225N. 


The Control routine 


The SCSI driver must be able to respond to several control 
calls, distinguished by their csCode parameter; some of them are 
described in TN28. They are: 


Killlo csCode=1 
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Verify csCode=5 
Format csCode=6 
Eject csCode-7 
ейсоп  csCode-21 
ccRun csCode=65 
SCSlCode сѕСоде=77 


Killlo is ignored (the driver operates synchronously and 
won't return before the I/O operation is completed), as are Verify 
and Format. 

Eject must be supported in some way. First, when the ROM 
code cannot boot off a volume, it will try to eject that volume; the 
driver code has to return with an error here, otherwise the 
Macintosh would keep trying to boot from this drive. Also, a disk 
inserted event is posted, so that later on , when the system comes 
up, the drive will be re-mounted. 

geticon, will return a pointer to an icon list (ICN#) corre- 
sponding to the disk icon, followed by a counted string identify- 
ing the driver. 

AccRun will post a disk-inserted event (see above); it will be 
called by the desk manager when the system comes up after boot 
time. After being called, it will clear thedNeedTime flag in the 
DCE so that no further calls are made. 

Finally, SCSICode is a control call that allows it to issue 
SCSI commands directly, with the parameters (SCSI command 
block pointer, its length, completion count, address of pseudo 
program) in the CSParam field of the parameter block. 

Status and Close calls are not supported. 


Read and Write 


The actual read and write calls pass through the Prime 
routine. It is mainly this routine, and SCSICommon that handles 
SCSI commands, that I had to modify to make Apple's driver 
work with my Q280. The modified routines are printed in listing 
one. 

Since the SCSI Read and Write commands only take an 8- 
bit sector count (512 bytes per sector), the author of Apple's 
driver decided to transfer the data in chunks of 64K maximum 
each. Furthermore, each such ‘chunk’ is transferred in 512 byte 
sub-chunks using the *looping' SCSI pseudo program described 
above. 

When I first tried to set up the Apple driver on the Q280 
without any modifications, the routine *almost' seemed to work, 
at least I could install my drive and see its icon on my desktop, 
although I couldn't boot. Nor could I read/write files larger than 
64K. Desperate, I looked through Technical Note #96, which 
describes SCSI handling and known bugs. 

The first problem was a well-known one with the Mac Plus 
ROM boot code: the Q280 was configured to enter the Unit 
Attention condition after a reset, and thus a read command right 
after that would fail. Although this problem could be overcome 
by changing the Unit Attention Enable bit on the drive with a 
Mode Select command, there was a second problem: The firm- 
ware that the Q280 used at that time took 4 seconds to recover 
after an SCSI bus reset, and since the Macintosh boot code issues 
resets in one-second intervals, the disk could never get ready for 
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the boot code to read the first blocks. This problem could only be 
solved by changing the firmware, which the local Quantum 
distributor eventually did. 

But there were other problems, this time in the Apple SCSI 
driver. The multiple-chunk transfer instruction block seemed to 
be one of them. TN96 says: "Don't use multi transfer TIBs. The 
SCSI Manager has trouble with losing bytes when executing 
more than one transferring TIB instruction within a single call. 
Try to code your TIB as simply as possible: SCNoInc followed by 
SCStop." 

Therefore, the Open routine was modified as described 
above. Although the problem was supposed to be fixed with 
System releases 3.2 or later, I found that a multi-transfer TIB 
wouldn't work even with more recent systems, and I still use the 
simple TIB shown above. 

The second problem was that the original driver transferred 
the data from/to the disk by consecutive Read or Write com- 
mands if the amount of data exceeded 64K bytes. Even though 
each of these commands was issued in the proper way, Getting 
the bus, Selecting the target, sending the command, doing the 
SCSIRead or SCSIWrite, and a SCSIComplete at the end, the 
driver seemed to be losing bytes when more than 64K of data 
were transferred. TN 96 cautions: "Multiple callsto SCSIRead or 
SCSIRBlind after issuing a command and before calling SCSI- 
Complete may not work." Although the situation was not quite 
like this - each Read was in fact completed before the next one 
was started - I decided to transfer all bytes with one single SCSI 
command. The 10 byte commands Read Extended and Write 
Extended can be used for this purpose. They take a 16-bit sector 
count in their command block, and thus allow the transfer of 
512*65536 = 32 Megabytes maximum. So until you’ ve upgraded 
your machine to more than 32 Mbyte, this driver should have no 
problems. 

Third, it seemed like blind transfers would not be accepted 
by my Q280. Therefore I changed the part of the SCSICommon 
routine that does the actual read/write so that only non-blind 
transfers would be made. This slows the driver down somewhat, 
but the overall performance (Disktimer II) is still about 60% of 
a Dataframe 40 XP on a Мас+. 

Letme quickly summarize the main modifications that have 
to be made to Apple's driver to make it run with the Quantum 
Q280 SCSI disk: 


- change the SCSI pseudo program so that only one transfer 
instruction is done. 

- remove the main loop of the Prime routine that reads/writes 
the data in several pieces. Replace it by a sequence of 
instructions that uses the SCSI Read/Write Extended 
commands so that all data is transferred in one block. 

- remove the option of doing blind reads. Only non-blind 
reads should be used. 


The modified Prime and SCSICommon routines are printed 


in Listing 1. The code there makes reference to variables and 
routines of the Apple SCSI driver, so you should have its source 
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at hand. The modified driver can be assembled with MPW or 
MDS; if you assemble it into a resource of type ‘SDRV’ and 
ID=128, the installer written in Mach? (listing 2) will accept it 
and write it out to your SCSI drive. The installer code should be 
self-explanatory after you’ve read the installation Strategy in 
V3#3. 

Since this article has made reference to quite a few different 
sources, ГИ summarize the recommended (or required) reading 
again: 


- Apple example SCSI driver source, version 1.0 (APDA) 
- Inside Macintosh: 
Vol. Il, Device Manager; Vol. ІМ, SCSI Manager 
- Technical Notes: 
28, Finders and Foreign Drives 
36, Drive Queue Element Format 
96, Known SCSI Bugs 
- MacTutor: 
V3#2 p.67, Tim Standing, Build your own SCSI hard disk 
V383 p.32, Jórg Langowski, SCSI device introduction 
V3#6 p.45, Tim Standing, SCSI formatting program 


The full source of a Forth SCSI driver is to follow in the next 
issue. See you then. 


Listing 1: Modification of Apple's Prime and SCSICommon 
routines for the Quantum Q280 


DiskPr ime 
Ад Cinput) - pointer to request parameter block 
А1 Cinput) - pointer to disk DCE 


P 

; Routine: 

; Arguments: 
P 

P 


; The “prime? entry point is used for drive read/write. 


; Within this routine, we use the following registers: 
‚ 09-01: temps 

03: Next Sector Number 

D5: Number of Physical Blocks Left to Xfer 

: Number of blocks to transfer this iteration 
A2: locals ptr 

АЗ: parambik ptr 

A4: DCE Ptr 


we t» Ve `. `. `. "` 
© 
о 


DiskPrime 
BSR.S — CkDrvNum ;сһеск for valid drive number, 
; Setup A2 & 01 
SF  TickleFlag(A2)  ;Remember that we've been 


, accessed. 


до the transfer. Our DCE ptr is іп A4, our locals ptr in A2. 
MOVE.L Ай0,АЗ ;зауе the ioparamblk ptr in АЗ 
,Calculate sector count (to D5) 
MOVE.L IOByteCount(A3),D5 ;how many bytes does he want? 


BEQ.S  DiskParmErr һе doesn’t want any! Ooops! 

LSR.L 8,05 ,convert bytes to 512-byte sectors 

LSR.L #1,D5 

61 AND.L  *"$0PIFFFFF,D5  ;meke sure it fits in 21 bits 

,Calculete starting sector number (to 03) 

MOVE.L DCtlPosition(A42,D3 ,Sterting byte position 

LSR.L #8,D3 ¿convert sector 8 to 512-byte sectors 

LSR.L 81,03 


;Renge-check this operation: 
ИТ (starting block number + block count) >= volume size 


¿then return IOErr. 

MOVE.L 03,00 ;copy starting sector 

ADD.L 05,00 ;add this request sector count 

CMP.L 01,00 ;Cblock after end of request ? 
; block after end of volume) 

ВСЕ PrimeErr 


;This request is valid. 
; Offset the starting sector * by the start of the partition 
ADD.L Offset(A2),D3 ;offset to the partition start 


“Сору buffer address to NextAddr(A2) 


MOVE.L 10Buf fer CA3), NextAddr (A2) 


;SCSI transfer is done by extended read or write. 


"T 


herefore no loop, like in the original code, is necessary. 


The maximum # of bytes transferred this way 

“will be 65535 sectors, i.e. 32 MBytes. 

“This should be well above the buffer size of the Mac for 
“some years to come. /JL 


63 


84 


65 


MOVE.W 05,06 ;Transfer 8 of sectors requested. 
; setup SCSI extended R/W block 


;Stuff command byte first 


LEA 5Ста(А2),А0 ;point at our command block 
MOVE.W "$2800, DB ;assume Read command 

CMP .B HarCnd, ioTrap+ 1(A3) ‚аге we writing? 

BNE.S 64 ‚по. 


MOVE.W #$2^00,00 : уез, do a Write command 
MOVE.W 00,(А02% ; put the command away. 


¿Stuff Starting sector number /JL 
MOVE. L D3,CA0D* ;put it into SCSI command block 
(clears logical unit number, too) 
;Stuff block count, and clear the reserved byte. 
LSL.L #8,D6 ;align D6 with cmd block structure 
MOVE.L 06,(А00% ¿put it away. 
CLR.B C(A0)+ ;clear the reserved byte. 


;Set up the SCSI “pseudo-program”. The SCSI manager 
T interpret this program during the trensfer. 
“Тһе program is very simple: 
f 61SCNOINC buffer, *bytes 
l SCSTOP 


7 
LEA SCSIPseudo(A2), Аб 
;point at the pseudo-progrem block 
MOVE.L NextAddr (A25, SCParam1CA2) 
;fill in “buffer” with the start address 
;of the caller’s buffer. 
LSL.L 81,06 ;convert "sectors*256 Cin 06) to #butes 
MOVE.L 06,5СРагап2(А0) ;fill in “bytes”: # of bytes 
LSR.L #1,D6 
LSR.L #8,D6 ;restore D6 


Фо the SCSI call for this iteration. 
MOVEQ 81,01 ;assume we're reading O0) 
CMP.B нам" Спа, ioTrapt 1САЗ); ere we reading? 
BNE.S 65 ев. 
MOVEQ 4-1,01 jno, we're writing. (X0). 


LEA SCSIPseudoC(A2),A9 ;роіпі at pseudoprogram 

LEA SCmd(A2),A1 ;point at SCSI command block 

MOVEQ 860,00 ;tick count to wait for completion 
MOVEQ 10,02 ¿length of command block 

BSR.S  SCSICommon ;до the xfer 

BNE.S  PrimeErr error in transfer. 

MOVE.L 06,00 ¿calculate * sectors xferred 
ASL.L #8,00 ; * 512, for 512 bytes per sector. 
ASL.L #1,D 


0 
ADD.L 00 ,NextAddr (A2) ;bump buffer pointer. 


;Let the parem block show that we finished. 


MOVE.L I0ByteCount(A3),D8 ;һе asked for this many bytes 
MOVE.L DØ, IONumDoneCA3) ;we did this many bytes! 
ADD.L — DO,DCtlPositionCA4) ;bump position pointer, too. 
BRA DiskOKDone ;ә11 done! 


;This is where we get to if we get ап SCSI error during Prime. 
m little intelligence here (геігу on certain kinds of errors? 
; would бе nice. 


PrimeErr: 
MOVEQ %10Егг,00 ;replace error code with an 1/0 Error 
BRA — DiskDone ;and return through our exit routine. 


Routine: SCSICommon 
Arguments: Our Id( A2) Cinput) - our SCSI ID. 
(AQ) (input) - the SCSI pseudoprogram (all set up) 
(А1) (input) - the SCSI command block (6 bytes) 
(А2) (input) - ptr to our locals 
DÜ.L — Сіприі) - the tick count we're willing to wait 
for completion 
014 (input) - sign of byte count we're transferring 
after the command (0 if none, + if read, - if write). 
D2.W Cinput) - Size of the SCSI command block 
StatWord(A2) Coutput) - 
- returned status from _SCSIComplete, if no err. 
MsgWord(A2) (output) - 
- returned Message from _SCSIComplete, if no err. 
DO .W (output) - result code (error if поп-0!) 


This routine is the common code for ап SCSI Operation. 

We set up the command block and the pseudoprogram, 

then call this routine to execute it. 

All the SCSIManager routines we^ll be using are stack-based 
functions which return an integer error code. 50 we "pre- 
push” result word, test it after each command, and pop it 
off after we're done Cor, [knock on wood] after an error 
occurs). 


“. $e wwe e Ce We We We We We We We We We Ve Be we We We We We We We We Be 


SCSICommon 
MOVEM.L D4-D6/A3-A4,-CSP) ,save regs 
MOVE.L 00,04 ¿save tick count in D4 
MOVE.L 01,05 ;save byte count in 05 
MOVE.W 02,06 ;save command size іп 06 
MOVE.L Аб, АЗ ;save the pseudocode ptr 
MOVE.L A1,A4 ;save the cmd block ptr 


CLR.W -CSP) ;reserve space for result code. 
;Arbitrete for the SCSI bus 

-SCSIGet ; "Hello?^ 

TST.W (SP) ;(did it work?) 


BNE.S  TergetErr ;(no... give up) 


;We have the bus... Select our target 
MOVE.W OurIDCA2),-CSP) ;push our target’s SCSI id 


-SCSISelect ;"Is there anybody out there?" 

TST.W CSP) ;(did it work?) 

BNE.S  TergetErr Спо... give up) 

;We've reached our target. Issue the SCSI command 

‘WOVE. L A4,-CSP) ;push address of SCSI command 

MOVE .W 06 -CSP) ‚ the block is this many bytes long 
-SCSICnd “do the command 

TST.W (SP) ;(did it work?) 

BNE.S Cleanup ;(no... go take care of the error) 


; If we have to transfer any bytes, execute the 
;_pseudo-progran to transfer them. 

“Since we’re going to do an SCSIComplete right away, 

¿we don’t need to check the error 

;Cbecause it would only result in а call to SCSIComplete...) 


TST.L 0 ;апу bytes to transfer? 
BEQ.S Cleanup ; no, skip this. 
MOVE.L A3,-CSP) ;yes, push pseudo-progrem address 


TST.L 05. ;Are we reading or writing? (- if writing) 
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BMI.S 61 ;br if writing. 


-SCSIRead ¿normal reads only. May be modif ied 
¿for other drives 
BRA.S Cleanup 
e1 .SCSIWrite о the Write. 
¿Clean up after ourselves, or find out why we got an error. 


;(the error so far is in (SP).W — it might be useful to look 
; at it). 


Cleanup: 
PEA StatWord(A2) 
PEA MsgWord(A2) 
MOVE.L D4,-CSP) 


‚де the status 
; end message words 
¿tick count we're willing to wait 


-SCSIComplete ;90 get ‘em 
TST.W CSP) ¿(did it work?) 
BNE.S  TergetErr ; Спо. Give up.) 


¿What were the Status bytes? 
MOVE.B StatWord+1(A2),D8 
BEQ.S SCSIDone 


умаз there an SCSI error? 
¿no error, just exit. 


АА this point, we should look at the “check sense status” 
;bit in the status byte - if it’s set, we could make а 
,recursive call to SCSICommon to get sense status. 

;But, since we'd only be returning ап 1/0 error anyway... 


Since this driver always executes fully synchronously, 
,we^ll probably never see the “busy” bit set, but we 
¿could probably retry in that case. 


Же got an error in contacting the target, or іп SCSIComplete. 
TargetErr: 
MOVE.W 8ioErr,(SP) ;if we can’t get bus or target. 


;Exit, stage left. 

SCSIDone: 
MOVE.W ($Р)+,08 урор error code 
MOVEM.L CSP2*,D4-D6/A3-A4 ¿restore regs 
RTS jand return (DØ and CCR reflect error). 


Listing 2: SCSI drive formatter/Installer 


N This program requires the SCSI command definitions 

V printed in V383. Only the actual installer code is listed 
here. 

V € Nov 1987 J. Langowski / MacTutor 


only forth definitions 
8150 mac also assembler 


variable numstring 20 vallot 
variable mydisk 


: input-number numstring 1+ 20 expect 
numstring number? drop ; 


: yesno 
BEGIN 
pad 32 expect pad с@ 

CASE ascii у OF 1 0 ENDOF 
ascii Y OF 1 Ø ENDOF 
ascii п ОҒ 0 0 ENDOF 
escii М ОҒ 0 0 ENDOF 

1 ENDCASE 

WHILE cr .” Enter y or n- * 
REPEAT 


: weit ( nticks | #ticks - ) 
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call tickcount -> "ticks 
BEGIN pause 
call tickcount #ticks - 
nticks › 
UNTIL 


2 


С SCSI routines follow ) 
: find.disk С finds the highest ID SCSI device ) 
8 1 do 
SCSIReset drop 60 wait 
SCSIGet drop 
i SCSISelect 0= IF i leave THEN 
loop SCSIReset drop 


; 
: get.disk find.disk mudisk ! ; 
: format 12000 format.blk myDisk @ doscsi 2drop ; 


: prep.noattn ( mode data ) 
scbuf 20 Ø fill 

( hex 1 

00000008 scbuf ! 
00000000 scbuf 4 +! 
00000000 scbuf 8 +! 
0002 1000 scbuf C * ! 
( decimal 1 


д 


( раде 0; unit а п disable ) 


: modenoattn 
ргер.поа {п 
16 modesel.blk 5 + c! 
120 modesel.blk myDisk 6 scbuf 16 doscsi.wb 
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variable ddm 512 vallot 
veriable dpm 512 vallot 
variable driver.block 2048 vallot 


: read.cap С - #blocks bytes.p.blk ) 
120 readcap.blk myDisk 6 scbuf 8 doscsi.rb 
abort” Can't read capacity” drop 
Scbuf ё scbuf 4 + e 


д 


: Show.cap геад. сар 
dup . ." byte blocks; total capacity is ^ 
1024 */ . ." K bytes.” cr 
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һех 
: create.ddm 
ddm 200 Ø fill 
4552 ddm w! 
read.cap дсп 2+ w! С block size ) 
ddm 4 + ! ( * of blocks ) 
0 ddm 8 + w! С device type ) 
0 ddm A + w! ( device ID ) 
8 ddm C +! (first data block ) 
1 дат 10 + w! C one driver to follow ) 
2 ddm 12 + ! C driver start block ) 
4 діп 16 * w! С driver із 4 blocks long 2 
1 ddm 18 + w! С and runs on Macintosh =1 ) 


: create.dpm 
dpm 200 0 fill 
5453 dpm w! 
8 dpm 2* ! С starting block of partition ) 
read.cap drop 8 - dpm 6 + ! С # of blocks ) 
*tfs! dpm А+! С TFS1 signature ) 
0 dpn E * ! 


MOVE.L 05,-САТ) 


decimal MOVE.L (A62*,D5 
MOVE.L (A62*,A0 
: read.ddm execute 
0 read.blk 2+ w! Ø read.blk 4 + c! MOVE.L (AT)+,D5 
1 read.blk 5 + c! RTS 
120 read.blk myDisk 6 ddm 512 doscsi.r END-CODE 
2drop 
: : mount.scsi 
install.driver 
: read.dpm read.dpm 
0 read.blk 2* w! 1 read.blk 4 * c! SysEvtMask 6 
1 read.blk 5 + c! 0 SysEvtMask ! 
120 read.blk myDisk 6 dpm 512 doscsi.r syshp.drvr 6 dpm myDisk 6 call.driver 
2drop SysEvtMask ! 
: write.ddn : zero.scsi 
Q write.blk 2+ w! В write.blk 4 + c! DQHeader qTail + 6 dQDrive + wê C drive 8 found ) 
1 write.blk 5 * c! ~ JL's Herd Disk” call DIZero 
120 write.blk myDisk 6 ddm 512 doscsi.w ; 
2drop 
: NEW.WINDOW Installer 
* SCSI Installer 0.9? Installer TITLE 
: write.dpm 50 20 300 480 Installer BOUNDS 
Q write.blk 2* w! 1 write.blk 4 * c! Document Visible NoCloseBox NoGrowBox Installer ITEMS 
1 write.blk 5 + c! 
120 write.blk myDisk 6 dpm 512 doscsi.w 1000 6000 TERMINAL Inst 
2drop 
Í : init.scsi ( | fmt - ) activate 
0 -> fmt 
: get.sdrv Installer dup CALL selectwindow 
*sdrv 128 call getresource dup CALL showwindow 
6€ driver.block 2048 cmove CALL setport 
1 cr .” Looking for SCSI devices...” 
get.disk 
: write.sdrv cr .* SCSI drive found at address * myDisk 6. 
0 write.blk 2* w! 2 write.blk 4 + c! cr show.cap 
4 write.blk 5 * c! cr .^ format disk? * 
120 write.blk myDisk 6 driver.block 2048 doscsi.w yesno IF 
2drop cr ." Do you REALLY want to erase this SCSI disk? ^ 
) yesno IF 1 -> fmt 
cr .^ Reformatting disk... * 
format 
.TRAP _newptr,sys $45 1E THEN 
hex 144 CONSTANT SysEvtMask THEN 
308 CONSTANT DQHeader modenoattn 
6 CONSTANT QTail create.ddm create .dpm 
6 CONSTANT 000гіуе write.ddm write.dpm 
decimal cr .” Device and partition descriptor maps written. " 
cr .” Reading SDRV resource ... ” 
VARIABLE syshp.drvr get.sdrv 
cr .” Writing driver ... * 
: install.driver ( | dstart dlength dbytes pointer - ) write.sdrv 
read.ddm mount .scsi 
ddm 18 + @ -> dstert fnt if 
ddm 22 + мё -> dlength zero.scsi 
dlength 512 * -> dbytes cr .” Directory zeroed.” 
dstart 256 /mod read.blk 2+ w! read.blk 4 + c! then 
dlength read.blk 5 * c! 60 wait bye 
120 read.blk myDisk 6 driver.block 512 dlength * doscsi.r I 
2drop 
dbytes MOVE.L (А62%,00 : SCSi.gO 
-newptr,sys ( get memory block in system heap ) Installer ADD 
MOVE.L A@,-CA6)  — pointer Installer Inst BUILD 
pointer Inst init.scsi 


IF driver.block pointer dbytes cmove 
pointer syshp.drvr ! 


2 


ELSE .” Not enough system heap for installation.” cr N use TURNKEY scsi.go filename to create 
THEN \ а turnkey application 
; 
CODE call.driver 2) 
f oett 5 oy 
8 
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Advanced Mac'ing 


Looking At Text From a Different Angle 


John D. Olsen is a Registered Public Surveyor in the State 
of Texas with approx 14 years experience in the field of Land 
Surveying and Civil Engineering. He is currently attending 
Texas A&M University in pursuit of a B.S. degree in Electrical 
Engineering. He is currently working at TAMU in the Veterinary 
Pathology Dept. at the School of Veterinary Medicine. He 
supports and maintains a network of Macs (approximately 35 
machines). He is working on two vertical market applications for 
the Macintosh. The first is a Scatchard PlotILigand Binding 
program. The second ‘on-going’ project is a CAD program for 
Land Surveyors and Civil Engineers involved in land division, 
development andlor surveying. 


"Yes, But Can You Type Upside Down?" 


It seems that no matter what we get in the way of library 
routines, ROM code, standard packages, etc... there is always 
something that we think ‘just should have been included’ as a part 
of the standard Toolbox routines. It seems one of the favorite 
things to pick on with the Macintosh is the TextEdit routines in 
ROM. 

Although Apple did *upgrade' the TextEdit routines with 
the introduction of the new machines most of us feel it is still 
lacking in several areas. The biggest complaint is usually the 
"limit' of 32K per record. Apple did extend TextEdit to handle 
styles in an integral manner, color text, and with several other 
goodies that tended to make our lives a little easier. 

One of the things I have heard few complaints about and 
which has admittedly not always been very high up on my wish 
list is the ability to place rotated text on the screen. It would be 
especially nice if I were able to type itin the same familiar manner 
that I use in editors, word processors, etc... I am involved in 
putting together some vertical market applications and have run 
up against this problem. For example, I need to be able to put 
labels on graphs and/or bodies of text in a CAD program. This 
text necessarily must be able to be read from the right side of the 
page. 

I learned early in my engineering courses that I should 
always completely define the problem and the givens before even 
attempting to begin a solution (to be perfectly honest I think we 
really all begin to try to solve a problem AS we are defining it but 
it sounds so much more professional to approach it in such an 
orderly fashion. Back to the problem at hand). 

The problem I had required that the text be rotated in even 
increments of 90 degrees. This is therefore a very specific 
solution as opposed to general rotation or what I refer to as a ‘free 
rotation’ routine; that is, it is not constrained by any particular 
angular increments as far as the user is concerned. 
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Fig. 1 Our example allows you to edit rotated text! 


I normally take the attitude that the general solution is the 
best solution for the obvious reason of re-usability of the code, 
adaption to other similar problems and so on. In this case I 
decided that performance was of the utmost importance and had 
the feeling that this problems solution would be CPU intensive. 
Talso had a premonition from the start that this program probably 
would not perform to my satisfaction if written in a high level 
language. 

Pascal is my language of choice when writing sizable 
programs. I felt rather anxious about the fact that at least a portion 
of this program might have to be written in Assembly language. 
Since my only experience to date was in debugging, I had a lot to 
learn. I was one of those naive souls who only read Assembly 
code when trying to track down some innocuous piece of code 
that had the audacity to crash MY PROGRAM and this only after 
everything else had failed. It seldom helped me solve my problem 
but as I found the exposure was of great value. 

The Plan 

The first thing I did was ask around to see if anyone I knew 
had already solved or attempted to solve this problem. I do not 
like to re-invent the proverbial wheel unless forced to do so. I 
talked to Greg and Scott of the MacHaxTM Group and they were 
not aware of any work to date (at least not any *non-proprietary' 
stuff) but did express interest and a great deal of encouragement. 
I checked the bulletin boards and found only one small piece of 
code that was completely written in Pascal with an unusual 
approach that used Copybits as the work horse. I tested it and 
found it took about 7-8 seconds to rotate a 3-4 sq. in. bitMap. This 
seemed to confirm my feeling that the core routine would have 
to be in Assembly Language. I also threw away the code I had 
downloaded. 


Having my problem fairly well defined I came up with 
several possible (?) solutions to the problem. I wanted this routine 
to behave similarly to DrawString if I could, so that I could 
simulate standard TextEdit routines by building on this basic 
module. 

The first solution that came to mind was a complete rewrite 
of the TextEdit routines but done in such a way that the user could 
select the orientation of the text to be displayed/edited. This had 
the added advantage of allowing me to add to MY TextEdit the 
things that I had always wanted. It sounded nice but it was quite 
a large feat. It also did more (a lot more) than I need it to do. It 
was like knocking out ant hills with atomic bombs - just a little 
overkill. I decided to file this idea in the back of my in case the 
solution I did come up with would be able to be built upon as the 
‘ultimate TextEdit’. 

The nextidea was to use offscreen bitMaps and an Assembly 
Language routine to rotate my text and then CopyBits it back to 
the desired position. This seemed like the best approach and was 
chosen as the method I would use. This had the added advantage 
of being able to rotate graphic objects as well. 

Greg Marriott and I discussed pre-rotating fonts as an 
alternative method to rotating the bitMaps on the fly (FONTS can 
be thought of as a long narrow bitMap). I could then develop a 
method for handling the new family of characters. This is an idea 
well worth exploring but I chose the former solution instead as I 
felt it was the simpler of the two and had the advantage of being 
smaller and more general. 

What | Did On My Summer Vacation 

My programs are written in Pascal with an external proce- 
dure written in Assembly Language to do the nitty-gritty of the 
rotation. I have included several examples of the program to 
show how it was tested during development along with a couple 
of ideas for implementation. The programs all function in the 
same manner although they do different things. 

The original program that I wrote for testing the routine 
simply rotates an ICON. There was actually a predecessor to this 
program that generated a stripe pattern and rotated it. I quickly 
found this to be of little use since the pattern was so simple. I was 
lucky enough to get all but the most trivial problems worked out 
and got what I expected when I FINALLY got the Assembly code 
done. ( More on that later.) 

The second program puts up a modal dialog box that acts as 
an editor. It has two or four windows depending on the version 
you choose to run. The two window version works better on the 
MacPlus as the performance of the four window degrades. The 
illusion of putting up text in all windows simultaneously works 
fine in the four window version on the Mac II or an accelerated 
machine such as my MacPlus with a Novy 020/881 at 16mhz and 
4 megs of wide (32 bit) memory. 

The third program is an example of using the routine the way 
I needed it to fill my needs for labels on my graphing and CAD 
programs. It also has an example of putting in picComments for 
high resolution output devices. I will discuss the flow and 
operation of this program. The others are included as examples 
only. 

How It Works 
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Fig. 2 Expanding text rotation to type upside down! 


I prefer the MPW environment for my work although 
occasionally I do use Lightspeed Pascal for some of my stuff 
(usually something small/quick). Most of this program is quite 
straightforward and is all in MPW's Pascal and Assembly Lan- 
guage. I don't use fancy tricks, bend the rules or rewrite anything 
that I don't have to. See listing 1 to follow along here. 

I'll begin at the top of the ‘MAIN’. The first thing we do is 
to Init our environment. This is only done once and some of this 
is not needed if you use Lightspeed Pascal but is a good thing to 
keep in practice (it is almost always the same). Then we need to 
setup our window to draw in, and our grafport. You should notice 
I'm paranoid about my code getting broken so I check for the 
screen size and menuBar height (thru screenBits and the low 
memory global: mBarHeightGlobal = $BA A) then move in from 
those so that it will work on all systems. I like to try to follow as 
many of the guidelines as I can, and if someone at Apple (or in 
this publication) can show mea “bullet proof' way of doing things 
you can bet I'll take advantage of it. One of the nice things about 
MPW is which I keep a bunch of ‘re-usables’ in my Worksheet 
(like the code to set the window size) that I can copy and paste in 
every time I start a new application. 

The Big Garbonza 

At this point I set the font, size and face through toolbox 
calls. This would more than likely be done either thru a menu, 
pop-up or dialog box in a real implementation but for now it is 
hard coded to keep things simple. Now we are ready for our call 
to then big garbonza, the one we've all been waiting for '*xDraw- 
String’. This is it - this is where itis all really done. (That is except 
for the Assembly Language stuff and yes I promise ГІ get to that 
if you will just hold your horses a little longer !) 

Ok - now back to ‘xDrawString’. I decided when I designed 
the Assembly Language code that I would pass a bitMap to the 
routine and get one back and that's all. No more parameters. The 
first stuff is to prepare for this call. After the call we copyBits our 
new rotated string (bitMap), set up the stuff for the picComments 
in case we need to copy to MacDraw or print to LaserWriter and 
cleanup. Thats it. 

Counting Hairs 

Let's look at it again in detail now. 

First we get the FontInfo so we can use some of the code in 
the record. I need the length and height of the minimum size 
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bitMap into which the string we want to draw will fit. We call 
StringWidth() to get the length in pixels. It doesn't get much 
easier than that. 

Ithen compute the height which will be equal to the ascent 
heightof the font plus twice the descent height. We use twice the 
descent height so that we get ‘white space’ all the way around and 
don't clip any danglies off. I then set my bounding rectangle up 
with a call to setRect. (These toolbox names are SO handy/ 
meaningful, don't you think ?) and calculated sizes. Now I have 
a rect but what I really want is to stuff it into the bitMap record 
that I am initializing. I can do this with a simple assignment to the 
‘bounds’ field. 

Now I call a neat little routine named ‘NewBitMapClear’ 
(another one of those re-usables) that will calculate my rowBytes 
and size for me. It then gets a pointer to the new block of memory 
(if available) and clears it. 


newPtrClear FUNC EXPORT 
IMPORT SAVERETA 1 


MOVE.L CSP2*,A1 
MOVE.L (SP)+,D0 
-NewPtr clear 
MOVE.L Аб, (SP) 
УМР SAVERETA 1 


ENDF 


The clearing (setting all bits to zero) is quite significant and 
will be evident why it is important later. Voila our sourceMap is 
set up. 

Next we do some book keeping for later. We get the address 

OÍ our current grafPort so we can get back to it later. We then go 

thru the normal gyrations of setting up our offscreen grafPort 

(with the bitMap we just created) and selecting it. We also make 

sure the text attributes are the same for this grafPort as our 

original grafPort since we set our desired text style for it. 
Draw That String - Tote That Bale 
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Figure No. 3 - Bitmaps: Before And After 
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We move from the origin of our new grafPort ( 0,0 ) to (0, 
myFontInfo.ascent ) that is we move along he left edge of our 
bitMap down (in a positive direction) to the ascent height of our 
font which puts us atthe baseline. Then we finally draw our string 
(keep in mind that this is all ‘offscreen’) 

OK, we've got our offscreen bitMap set up so now I will go 
ahead and set our port back to where we started: 


SetPortC origPort ); 


Let's recap to this point: 

1. We init all the managers 

2. Set up our offscreen bitmap/grafport 

3. We copy text attributes from orig-»new 
4. Move to where we want the string 

5. Draw that string offscreen 


Ok so we draw our string offscreen, call our assembly 
language stuff to wave the magic wand. Then we copyBits it to 
the correct (Original) grafport. The rest of the example code is 
dedicated to setting up picComments and clean-up. Since these 
items have been covered in detail before I'll leave them alone for 
now. Just keep in mind that picComments have become a very 
important part of all code that has anything to do with images that 
may be printed. This is so we can take advantage of the high 
resolution output devices primarily (LaserWriters, plotters, 
transfer to object drawing programs). 

Off To The Land of The Unknown 

Now everything was primed and ready to go so we could call 
our Assembly Language routine. This is the routine that does 
ALL the real work. It must make a copy of our bitMap ONE BIT 
AT A TIME (this is not completely true but we'll get to that in a 
minute). Obviously this is not the kind of thing to do in a high 
level language because of the tremendous overhead. 

There was only one small complication to doing 
this procedure. I had NEVER written in assembly 
language. 

With this challenge in front of me and a desire to 
really understand what I was looking at when I opened 
up TMON, Nosy or a dumpcode file I was off to my 
si! library. I had read all the standards for Macintosh 
programing and remembered the section in the back 


зо see НЫ 


“my Scott Knaster's book “How to Write Macintosh Soft- 
"B, ware” on how to read assembly code. I got it out read it 
ІШ again and realized that understood a lot of the individ- 
,8 5 ualinstructions and what they did, the various address- 
E," ing modes, etc... The thing I didn't understand was 
"ES — HOW/WHERE TO START. 

"Еи Banging My Head Against Тһе Wall 


see 


>. cee 
$: ses 
= 


I decided the only thing to do was to enlist some 
help. 

I went to Greg Marriott of the MacHaxTM group 
and explained my predicament. He agreed to help me. 
We spent about an hour talking about the same stuff I 
had just gone over. He also told me that he had a similar 
problem when he sat down to write his first Assembly 
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This figure shows how we can pick up "extra Баддаде" 
when we rotate the bitMap . This is more efficient than 
checking for the end condition each time thru the 


inner loop. 


Figure No. 4 - BitMap's Extra Baggage 


language routine. We spent the next hour writing a small proce- 
dure and talking. That hour was the most enlighting time I had 
spent in my quest to write this code (or at least it seemed that 
way). 

When І get to a point in my programing where it seems I just 
can’t figure out how to do something it usually helps to either go 
on to something else or quit for a while. That is good unless you 
don’t really know where to start. 

Горе going thru my code will help someone else get past the 
point where I was hung up. I will discuss the general design and 
action of this routine and then go thru it step by step. If you have 
alot of experience in writing Assembly code the step by step will 
be quite boring ( I suggest you skip on to the next section after 
Watching the Grass Grow). 

How & Why of My Asm 

The reason we use assembly code is that we want control (in 
this case at the bit level) without all the overhead. When you get 
control you are in COMPLETE CONTROL. The Mac is not 
nearly as forgiving when working at this low level. That means 
instead of hitting a pot hole in the road you've hit a tree or gone 
off a cliff. 

This routine maps all the bits in the sourceMap to the 
destMap while rotating the map 90 degrees in a clockwise 
direction. 

I pass the sourceMap and destMap to the asm routine. The 
routine expects both of these to have been declared as bitMaps 
but only the sourceMap to have been initialized. 

I handle the math involved in computing the new rectangle. 
The width of the sourceMap is a multiple of words (16 bits or two 
bytes) wide. That is the definition of rowBytes. The destMaps 
width, which is not necessarily on an even word, will be set to an 
even word. Rather than deal with end conditions I leave the 
height of the DestMap (which is the same as the width of the 
sourceMap) on an even word boundary. 

In the worst case we could end up rotating an extra 15 bit 
wide strip along the right edge. By doing this extra work we save 
an extra test for each bit. For small bitMaps the actual ‘extra’ area 
is small anyway. For large bitMaps the ‘extra’ area is a small 
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destMap's 
Extra Baggage 
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even number of words 


| rt.bounds - | Es on word 
lt.bounds max 15 bits 


percentage of the whole. 

I setup this bitMap each time thru the routine, therefore the 
programmer is responsible for disposal of this temporary map. I 
chose to do this math and memory allocation in the Assembly 
routine. If the user doesn't like this it would be trivial to remove 
and handle in high level. 

The rotation routine starts at the top left corner of the 
sourceMap and moves across a word at a time. 

I map to the lower left corner of the destMap and move up 
a word at a time. This is done with 16 words for each word of the 
destMap. After I reach the top I move over a bit and do it again. 

I test each bit for being set and only if true do I get a word 
from memory and set its corresponding bit. This is possible 
because I clear memory when I allocate the space for the bitMap. 
This saves moving memory unnecessarily. This is the mostcostly 
portion of the routine because if all bits were setin the sourceMap 
we would have to get each word from memory and return it 16 
times. 

Its as simple as that. Nothing real complicated is being done 
here; it is just time consuming. 

The Better Mousetrap 

This can all be done in much smaller increments in registers. 
This will save all the moving in and out and in and out of each 
word. It should make the performance increase by at least an 
order of magnitude. 

Iknow ofa fellow Aggie here in Bryan/College Station who 
is working on such a routine and article and look forward to 
reading about his approach. Until then I will use my stuff. 

Watching The Grass Grow 

As promised I will go thru the code a chunk ata time for those 
who wish to avoid the anguish that I went thru. 

First we have another little procedure (actually a Function) 
we should discuss ‘ пемРиСеаг. The only real difference in 
this and newPtr is that we call this register based routine with the 
*clear' parameter. This saves the step of calling EraseRect or 
something similar to set all bits to zero. This is the code that does 
that for us: 
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newPtrClear FUNC EXPORT 
IMPORT SAVERETA1 


MOVE.L (SP)+,A1 
MOVE.L (SP )+, DØ 
-NewPtr clear 
MOVE.L Аб, (SP) 
JMP SAVERETA 1 


ENDF 


Lets talk about format since we are getting down to the nitty- 
gritty. The first thing I should mention about the format of our 
text file is that it is ‘line based’. That is each command/operation 
is on a single line as opposed to a language like pascal that is 
procedure based. 

The first column is for labels only. Period. Nothing else. If 
you want to get screwed up put something else there and watch 
your error list grow out of sight. There is one exception, that being 
comments, which can go anywhere. 

There are several things to remember about comments. The 
first is that they start with a semi-colon. The nextis that they don’t 
have a terminating character so although they can be on the same 
line they can’t be embedded. The only other thing I want to 
mention is that with Assembly code you should comment every- 
thing. Use them excessively. It will save you a lot of time later. 

I will get off my soap box now and get on with it. From time 
to time I will mention some of the things I ‘discovered’ or found 
to be pitfalls. 

The first part of the code sets up our constants, stackframe 
and saves our registers so we can get back to the state we were in 
when we started. This is something you will almost always do. 


Des (Мар EQU 4+4 
SourceMap  EQU DestMap + 4 


; Offset to dest bitmap ^ 
; Offset to source bitmap ^ 


create local stack frame, and save some registers 
; маке room for dest rect to be passed back 


link аб, 80 
моует.1 d3-d7/a2-85,-Csp) 


; Set up а stack frame 
, save reg pascal may need 


The next couple of lines get us pointing to the bitMaps by 
getting the address off the stack. This is done by using a 
displacement off the stack pointer. 


поуе.1 SourceMap(Ca6),a1 


; point to the source BitMap 
move.l DestMap(a6),a2 


; point to the dest BitMap 


Next we will compute the size of our destMap in preparation 
for filling out its record and getting it some memory. Notice the 
logical shifts instead of divides and multiplies when working 
with powers of 2. This save several cycles. 


move.w boundstbottom(al),d7 
.  Sub.w  bounds*topCa12,d7 
d7 


; get bottom and put in 97 

; bot - top = height, put in 

move.w dT7,d0 ; Save а copy of height 
; rnd = Cheight+15)/ 16 

; edd 15 to the ht, put in 97 

; divide by 16 

; Multiply by 2 = rowBytes of 


eddi.w 815,47 
lsr 4441 
191 414 
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; dest bitMap 
Isr 81, 99 ; divide height by 2 
move.w (40,02 ; make а copy of height/2 for later 
move.w boundsttop(al),d5; get ‘top’ of source rect 
edd.w | 40,05 ; 95 now contains vert component 


; of ctr pt 
; compute the width of src rect & 

‚ put in 94 
move.w boundstright(al),d3 ; get right and put in d3 
Sub.w  boundstleft(a12,d3 ; B ы width, put 

i n 
Isr 81,43 ; divide width by 2 
move.w 03,01 ; маке а copy of width/2 for 
Jeter 

move.w boundstright(al),d4 ; get rt of source rect 
Sub.w  d3,d4 ; 04 now contains horiz 


; component of ctr pt 
; compute 'top' 
move.w d5,d3 get & copy of ctrPt.v and put 
in d3 
Sub .w 
swap d3 


91,93 ; ctrPt.v - width/2 = ‘top’ in d3 
move ‘top’ to hiword 
compute ‘left’ 
get a copy of ctrPt.h and put 
; in loword of d3 
92,93 ; ctrPt.h - height/2 = ‘left’ 
у in loword of d3 


Wwe We Be We Be We 


move.w (44,03 


Sub .w 


, № now have ‘top’ in hiword & ‘left’ in loword 93 
compute ‘bottom’ 

get a copy of ctrPt.v in of d3 
ctrPt.v + width/2 = ‘bottom’ in 93 
move 'bottom^ to hiword 

compute ‘right’ 

get а copy of ctrPt.h and put 

in loword d6 

ctrPt.h + height/2 = “right” 

in loword d6 


move.w d5,d6 
add.» 91,96 
swap d6 


move.w (44,06 


add.w 42,06 


Kk. We We Be We We Be We We 


Note that some of the blocks of comments have been 
stripped out of the code so we can repeat it here without getting 
too carried away. 

I have already assigned the rect data directly. That is, I put 
in the structure directly since we can do that here and avoid the 
overhead of a trap call. This is something that some programmers 
do not take advantage of. There are two reasons I can think of for 
this. 

The first is that the _SetRect trap is much smaller (fewer 
lines of code). It also doesn’t take much thinking to put it in. 

The second and probably more important is that the traps 
tend to make the code more readable ( easier to understand). 

The next section of code fills in the rest of the bitMap 
Structure for us. 


; assign data to dest bitMap structure directly 


^ pove.w d7,rowBytes(a2) ; put in rowBytes direct for 


; dest bitMap 


move.| d3,bounds*topLeft(e2)  ; put the coord pair in 
; direct 

move.| d6,bounds+botRight(a2) ; put the coord pair in 
; direct 


move.w (7,00 ; put rowbytes in 99 


mulu rowBytesCa1), 90 ; mul rowBytes src*dest = dð 

181 83,00 ; Multiply dó by 8 for size of 
; dest bitMap 

-NewPtr clear ; allocate size of dest bitMap 
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(а2 pts to it) 


поуе.1 af,baseaddr(a2) — ; move contents of að to 
| 
7 


baseAddr field 
‚ of dest bitMap structure 


Notice that I repeated the call to _NewPtr with the clear 
parameter in the code. We could have done this with a subroutine 
but unrolling the code again saves some time and this is a small 
piece of code. 

The next chunk of code actually gets to the heart of the 
matter. This is where we start doing all the swapping and testing 
of bits. We are all set up and ready to roll. 


| lea localVars,a0 

: initialize dð to contain the pointer to the srcMap 
move.w rowbytes(al),dÜ ; get rowbytes of srcMap 

; get regs pointing to bits 


move. | 
move. | 


(812,81 
(822,83 


; al pts to BITS of src bitMap 
; 93 pts to BITS of dest bitMap 


Ichose tolet the compiler compute the addresses of my local 
variables for me. This does not cause any additional overhead as 
itis all done at compile time. I load the address of the beginning 
of my variables into a0 and access all of them via offsets off this 
register. I could have used one of the nicer features of MPW that 
allows the user to build records. The effect is the same. I chose to 


roll my own because it was something I already understood. 


clr.1 di 
move.w 90,91 


; clear di 
; load rowBytes of 5гсМар 
; CrowBytes of srcMap = ht of 
; destMap 
ls].w 83,91 ; multiply by 8 to get ht of 
; destMap when rot’d 
; multiply by rowbytes(destMap) = 
; "words in 
) 


mulu.w 47,01 


sub.w (1,01 ; destMap less one row 

8949.1 аз,41 edd the computed offset to the 
; baseAddr of destMap 

поуе.1 di,lowerLeft-localVers(a0) ; init lowerLeft 


The previous section of code computes the lower left corner 
of the destination bitMap. This is the ‘master reference point’ for 
all of the addressing computations for the destMap. All addresses 
are computed as an offset from this comer. This offset is in the 
form of a bit and rowbytes times the number of rows. This is not 
computed each time thru though. It is kept up with counters 
which are needed anyway. 


; 
; init wordCount to zero 


move.w t€'ü,wordCount- localVersCa£) 
; Set wordCount to 
;zero before we start 


; 
; init colmLoop counter 


move.w (7,02 
Isr 81,92 


; get rowBytesCdest) 

; divide by 2 - d2 now contains the 
; outer counter 

move.w d2,colmCount-localVars(a8) ; put the max 


14 


; value away for reference 
; Set d2 to zero since we use it 
; for the counter 


moveq.] #9, 42 
со1т оор 


; this is the outside loop 
' move.w "15,d4 — ; init colmBitLoop counter to 15 
поуе.1 lowerLef t- localVarsCa0),currentWord-localVers(Ca) 
; init currentWord 
со1тВі оор 


The previous section of code sets up the labels for all the 
loops and initializes the counters. This is where it got confusing 
to write. I made a rookie mistake in my first attempts to code this 
inner section. I tried to code straight thru instead of setting up the 
loops,then going back and filling them in from the inside out. 
Once I changed my approach to looking at a couple of lines at a 
time I had it licked. 

We finally get to the point next where we are testing bits and 
getting a word out of the destMap if true. We then set the 
appropriate bit and put the word back. Again we only get the word 
if we need to SET a bit because they are all cleared to start with. 
This is critical to the performance. 

We work completely thru a source word at a time - easy. 


move.w (al),d3 ; get а word to rotate into 93 
eddq.w #2, wordCount-localVars(a8) ; add 1 for ea word 


moveq.1 80,46 ; clear d6 
move.w 815,06 ; initialize the inside (bit) loop 
; counter 


innerLoop 


we test each bit (15-›0 ie. 1t tort) if it is set we worry 
about going out and setting it in destMap otherwise we 
just increment the counters and test the next bit (cause 

we cleared them all at init) 


we We We Ve We ә 


btst 46,43 ; test bit pointed to in the 

; current src word 

; by the inner (bit? loop counter 

beq NoB i tToChange 

sub.]  d7,currentWord-localVarsCa?) ; Subtract 
; rowBytesCdestMap) from 
; current word 

дога 46, іппегіоор ; keep looping (thru bits) till dô = -1 


8094.1 82,81 ; point to the next word in srcMap 


The next piece of code is the bookkeeping section that keeps 
us moving thru both of the bitMaps in synch. The only thing 
tricky is the slightly unorthodox use of a dbra which actually is 
used more as an independent counter than a loop. That is we have 
a label up top that we getto from two places and the second place 
gets control only when we exit the dbra ‘counter’. 


поуеа.1 currentWord-localVers(Ca0), a2 

; get addr of currentWord 

; get currentWord 

; Set proper bit in currentWord 


move.w (a2),d5 
bset d4,d5 
move.w d5,Ca2) 
; put the currentWord word back 
; into destMap 
noBitToChange 
doneWithSrcWord 
cmp wordCount- localVarsCa) , 00 
; стр wordCount to rowBytes-ere we done with а row ? 
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bne 
doneWi thRow 
move.w %%,wordCount-localVars(ad) 
; reset wordCount to zero 
lowerLef t- 1ocalVarsCa),currentWord-localVars(aQ) 
; re-init currentWord 
dbra d4,colmBitLoop ; go thru the bits (15-20) in the 
; destMap - then exit and do it 
, again for rowBytes/2 times 


гой оо ; по - do another word 


move. | 


doneWi thDestWord 

2994.1 $2,lowerLeft-localVarsCa0) ; this moves us 
; into the next 
; 'column^ of bits in the destMap 
; add 1 to the colmLoop counter 
colmCount-localVars(a®),d2 ; are we done yet ? 
colmLoop ; no - do it again 


addq.w 81,2 
стр 
bne 


Theonly thing leftto do is our clean-up. Then after our clean- 
up code is the stuff to set up the local variables (pretty straight 
forward stuff). 

Has The Jury Reached a Verdict? 

With the introduction of the new machines life has once 
again gotten just a little more complicated. We used to be able to 
think of a one to one relationship for bits and pixels. Life was so 
easy then (HA!). Anyway, now with the advent of color we have 
to be careful and make sure we write for the correct machines. 

What am I getting to ? This code will work only on the old 
machines and for the ‘old color model’. It will be relatively easy 
to adapt to the eight bit color mode in the new model but thats 
another article. 

If I were going to give someone some tips before they started 
to write their first assembly language routine as I just did I would 
say “МаКе it work first'. Now that sounds rather paradoxical I 
know. What I mean by it is that you should start small and work 
up. Make you code do the bare minimum first then after it is 
working enhance it. 

Ра Like To Thank The Academy... 

If you're real lucky you'll have someone around to ask 
questions of. I was lucky. I had Greg Marriott. He forced me to 
learn this stuff - No spoon feeding here. I thank him for that. I 
know I asked some really dumb questions sometimes. I would 
also be remiss if I did'nt mention Scott Boyd. He came up with 
the idea for the quasi-editor rot4Edit in a brainstorming session. 

If you don't have anyone around or would like to comment 
on my code (please don't flame me to bad - this was my FIRST) 
or if you have a neat idea that I could implement with this code 
contact me at MCI JOLSEN or AppleLink 00795. 

Usethis code if you like itand let me know what you do with 
it. 

Listing 1 rotString.p 
PROGRAM rotStr ing; 


0000000000000000000000000000000000 
rotString by John D. Olsen 
for 
MacTutor Magazine 
€ Jan 1988 
0000000000000000000000000000000000 
) 


USES 
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($LOAD MemQukOSToo Pack) 
Memtypes, Quickdraw, OSIntf, ToolIntf, PackIntf; 
($LOAD} 


CONST 
picDwgBeg = 130: 
picDwgEnd = 131; 
Tex tBegin = 150; 
TextEnd - 151; 
Str ingBegin - 152: 
Str ingEnd = 153; 
TextCenter - ]54; 
TYPE 
TTxtPicRec = packed Record 
tJus: Byte; 
tFlip: Byte; 
tRot: integer; 
tLine: Byte; 
tCmnt: Byte; 
end; 
TTxtPicPtr = ^TTxtPicRec; 
TTxtPicHdl = *TTxtPicPtr; 
TTxtCenter = Record 
y, x: Fixed; 
end; 
TTxtCenPtr = ^TTxtCenter; 
TTxtCenHd] = ^TTxtCenPtr; 
VAR 
thehandle : handle; 
windowRect, sourceRect, destRect : rect; 
myWindow : windowPtr; 
SourceMap, destMap, tempMap : BitMap; 
myLabelStr : str255; 


FUNCTION NewPtrClearC theSize: size ) : Ptr; EXTERNAL; 
PROCEDURE RotateC srcMap, destMap : BitMap ); EXTERNAL; 


PROCEDURE NewBitMapClearC VAR theBitMap : BitMap 2; 
BEGIN 


WITH theBitMap, bounds DO 
BEGIN 
rowBytes := ((right - left + 15) DIV 16) * 2; 
baseAddr :- NewPtrClear(rowBytes * (bottom - top)); 


IF MemError © noErr then beseAddr := NIL; 
END; 
END; (NewB i tMapClear) 


PROCEDURE Open indow; 


CONST 
mBarHeightGlobal - $8AA; 
VAR 
Screen : rect; 
mBarHeight : Integer; 
MemoryPtr : “Integer; 
BEGIN 
MemoryPtr :- Pointer( mBarHeightGlobal ); 


mBarHeight := MemorgPtr^; 
Screen := ScreenBits.bounds; 


SetRect( windowRect, screenBits.bounds.left + 5, 
screenBits.bounds.top * mBarHeight * 25, 
screenBits.bounds.right- 5, screenBits.bounds.bottom - 5 ); 


myWindow := NewWindowC NIL, windowRect, ‘Text Rotation’ 
, true , documentProc, windowPtrC -1 ), false, longint( Ø 2); 
SetPort( myWindow ); 
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END; (OpenWindow) 


PROCEDURE xDrawString( myLabelStr: str255 ); 


VAR 
myFontInfo: FontInfo; 
strWidth, mapLength :INTEGER; 
mapHeight, xOffset, yOffset : INTEGER; 
sourceMap, destMap : BitMap; 
sourceRect, destRect, myClipRect : Rect; 
MyRgn: RgnHandle; 
origPort, offScrGrafPort : GrafPtr; 
textHandle, centerHandle : Handle; 
Tx, Ty: fixed; 


BEGIN 

GetFontInfoCmyFontinfo); 

strWidth := StringWidthCmyLabelStr ); 

mapLength := ((strWidth - 1) div 16 + 1) * 16; 

mapHeight := myFontInfo.ascent + 2 х (myFontInfo.descent ); 
SetRect(sourceRect, 0, Ø, mapLength, mapHeight); ( set up 


our offscreen bitMep ) 


sourceMap.bounds := sourceRect; 
NewBitMapClear( sourceMap 2; 


GetPortCorigPort); 
( create new grafPort to make sure things stay clean ) 
offScrGrafPort := GrafPtr(NewPtr (sizeof (GrafPort))); 
OpenPor tCof fScrGrafPor t); 
of fScrGrafPort*.portRect := sourceMap.bounds; 
SetPortBitsCsourceMap ); 
WITH offScrGrafPort* DO 
BEGIN 

txFont := origPort^.txFont; 

іхбіге := origPort^.txSize; 

txFace := origPort^ . txFace; 
END; 


GetFontInfoC myFontInfo 2; 

( draw the string we want rotated into our temp bitMap ) 
МоуеТо( 0, myFontInfo.ascent); 

DrawString( myLabelStr 2; 

SetPort(origPort?; ( set our port back to the original } 
RotateC sourceMap, дес (Мар 2; 

( rotate {һе offscreen bitmap } 


destRect := destMap.bounds;( going to draw it ? ) 
WITH destRect DO( offset to 10,10 ) 
OffsetRect( destRect, -left, -top 2; 
OffsetRectC destRect, 10, 10 ); 
(set up picComments ) 
textHandle := NewHandle(sizeof(CTTxtPicRec)); 
centerHandle :- NewHandle(sizeof (TTxtCenter 22; 
WITH TTxtPicHdlCtextHandle2^^ DO 
BEGIN 
tJus := 2; (center) 
tFlip := 0; (no flip) 
tRot := 270; (rotate 270 degrees) 
tLine := 1; (single spacing) 


tCmnt := 0; 
END; 
HLock(centerHandle); 


WITH TTxtCenHdlCcenterHandle2^^, destRect DO 
BEGIN 

Ty :- FixRatio(bottom - top, 2); 

Tx := FixRatio(right - left, 2); 


xOffset := - strWidth div 2; 
yOffset := (myFontInfo.ascent - myFontInfo.descent) div 
2; 
x := FixRatioC-xOffset, 1); 
у := FixRatioC-yOffset, 1); 
MoveToCleft + HiWrd(Tx) + xOffset, top + HiWrd(Ty) + 
16 


yOffset); 
END; 


PicComment(picDwgBeg, 0, nil); 

PicComment(TextBegin, sizeof(TTxtPicRec), textHandle); 
PicComment(TextCenter, sizeof(TTxtCenter), centerHandle); 
HUn lock (centerHand le); 

DisposHandleCcenterHandle); 

DisposHandle(textHandle?); 


SetRect(myClipRect, 0, 0, 0, 0); ( set to “nada” ) 
ClipRectCmyCl ірКес 0; 


( this just puts the string into the picture ) 
DrawStr ing(myLabelStr); 


( now set the clipRect back and draw the rotated bitmap } 
ClipRectCorigPort* .portRect); 


CopyBitsCdestMap, origPort^.portBits, destMap.bounds, 
destRect, srcOr, nil); 


PicCommentCTextEnd, 0, nil); 
PicComment(picDwgEnd, 0, nil); 


(clean up our mess) 
ClosePortCof f ScrGraf Port); 
DisposPtr(ptrCof fScrGrafPort)); 
DisposPtr(sourceMap .baseAddr 2; 
DisposPtr(destMap .baseAddr ); 
SetClip(MuRgn); 
DisposeRgn(MuRgn); 

END; (xDrawStr ing) 


(oooooooo MAIN 0000000000) 
BEGIN 
FlushEventsCeveryEvent, 8); 
InitGraf(@thePort); 
InitFonts; 
Ini tWindows ; 
InitMenus; 
InitDialogs(NIL); 
InitCursor ; 
OpenWindow; 
TextFont(Geneva); 
TextSizetC 12); 
TextFace((]); 
myLabelStr := ‘Looking at text from a different angle’; 
xDrawString( myLabelStr 2; 
REPEAT UNTIL button; 
DisposeWindowC myWindow 2; 
END. 


Listing 2 Rotate.a Assembly Code 
0000000000000000000000000000000000 

Rotate by John D. Olsen 

for 
MacTutor Magazine 
€ Jan 1988 

0000000000000000000000000000000000 

INCLUDE ‘SysEqu.a’ 

INCLUDE  ‘Traps.a’ 

INCLUDE  ‘QuickEqu.a’ 


newPtrClear FUNC EXPORT 


IMPORT SAVERETA 1 
MOVE.L (ӨР2%,А1 
MOVE.L (SP2*,D0O 
-NewPtr clear 
MOVE.L A2,CSP) 
JMP SAVERETA 1 
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ЕМОЕ 
Rotate PROC EXPORT 


PROCEDURE Rotate (sourceMap, destMap : bitMap ) 
given а source and destination bitmap rotate it CCW 98°.. 
bitmap can be of any size, align on word boundaries (v & h) 


að = result of _newPtr call | d = size of bitMap 
al = ptr to src bitMap | dis width/2 (source) 
82 = ptr to dest bitMap | d2 = height/2 (source) 
a3 - dest bits | d3 = left | top 
= copy of dest bits | 94 = ctrPt.h 
a5 - not used | 95 = ctrPt.v 
аб = not used | d6 = right | bottom 
87 = not used | 97 = rowBytes of dest bitMap 
' ЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 
‚ Ж x 
; *|nitialize destination bitMap (destMap), etc.. x 
. Ж x 


М 

; 

; 

; 

; 

; 

д 

; 

М 

; 

; 84 
‚ 

; 

; 

; 

7 

7 

М 

; ЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 

; parameter offsets 

7 

Des (Мар EQU4+4 ; Offset to dest bitmap ^ 
SourceMap EQU DestMap + 4 ; offset to source bitmap ^ 


create local stack frame, and save some registers 

; make room for dest rect to be passed back 

' ink аб, #0 ; Set up а stack frame (no bytes) 
movem.| — d3-d7/e2-85,-(sp) ; save registers for pascal 


move.] SourceMap(a6),81 ; point to the source BitMap 
move.lDestMap(a62),82 ; point to the dest BitMap 


compute height of source BitMap rounded up to nearest word 


`. 


move.w bounds+tbottom(a1),d7; get bottom and put in d7 
Sub.w bounds*top(al),d7; bottom - top = height, in d7 


move.w 47,00 ; save а copy of height for later 

; rnd = Cheight+15)/16, follows: 
addi.w 815,07 ; edd 15 to the height, put in 97 
lsr 84047 ; divide by 16 


1681 81,07 ; Multiply by 2 = rowBytes of dest bitMap 
97 now contains rowBytes of dest bitMap 
now compute the destRect for dest bitMap 


compute center point of Source rect 

note the center points are not necess. the 

same in the vert dir. relative to srcMap 
because of rounding that follows Ci.e. height 
of srcMap is dir. prop. to RowBytes of destMap) 


we We "€. We We We We We We ә о 


Isr 81040 ; divide height by 2 

move.w 00,02 ; make a copy of height/2 for later 

move.w boundsttop(al),d5; get ‘top’ of source rect 

add.w 90,95 ; % now contains vert component of ctr pt 
; compute the width of src rect & put in 94 

move.w boundstright(ai),d3 ; get right and put in d3 

Sub.w bounds*left(al),d3 ; right - left = width, in d3 

lsr 81,03 ; divide width by 2 

move.w 03,01 ; make а copy of width/2 for later 

move .w boundstright(al),d4 ; get right of source rect 

Sub.w d3,d4 ; d4 now contains horiz component of ctr pt 


now get center point and compute bounds for dest bitMap 
height апа width are reversed now Гог the 2 bitMaps 
left :=ctrPt.h - height/2 

top :=ctrPt.v - width/2 

right :=ctrPt.h + height /2 


we We We We `. "`. 
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; bottom:=ctrPt.v + width/2 
; SetRect(rect, left, top, right, bottom) put data in direct 
to avoid the overhead of a trap call 


М 

; compute ‘top’ 
move.w (5,03 
Sub.w 41,03 
swap d3 


; get а copy of ctrPt.v and put іп d3 
; ctrPt.v - width/2 = ‘top’ in d3 
; move ‘top’ to hiword 
; compute ‘left’ 
move.w d4,d3 ; 
sub.w d2,d3 ; 


get а copy of ctrPt.h and put in loword d3 
ctrPt.h - height/2 - 'left^ in loword d3 


we now have ‘top’ in hiword & ‘left’ in loword d3 

compute ‘bottom’ 
move.w d5,d6 ; get а copy of ctrPt.v in of d3 
add.w (41,46 ; ctrPt.v + width/2 = ‘bottom’ in d3 
swap dô ; моуе 'bottom^ to hiword 

; compute “right” 

; 

д 


we Ge 


move.w 04,06 ; get а copy of ctrPt.h and put in loword d6 
add.w 92,46 ; ctrPt.h + height/2 = ‘right’ in loword 46 
we now have ‘bottom’ in hiword & ‘right’ in loword d6 
assign data to dest bitMap structure directly 
move.w d/,rowBytes(a2) ; put rowBytes for dest bitMap 
поме. 1 d3,bounds*topLeft(a2) ; put coord pair in direct 
поуе.1 d6,bounds+botRight(a2) ; put coord pair in direct 
move.w 07,00 ; put rowbytes in 99 
mulu rowBytes(a1),dð ; multiply rowBytes src*dest = dð 
151 13,00 ; Multiply 90 by 8 for size of dest bitMap 
-NewPtr clear ; allocate size of dest bitMap (a2) 
move.] a%,baseaddr (a2) 
move contents of ай to baseAddr field 
of dest bitMep structure 


we We 


we We 


; ад = baseAddr for our locals 
00 = rowbytes of srcMap 
al = points to bits of src bitMap 
| dis width/2 Csource) 
82 = ptr to dest bitMap | d2 = height/2 (source) 


`. 


; 83 = dest bits | d3 = current word srcMap 

; 84 = | d4 = copu of width of srcMap 

; 85 = not used | d5 = current destMap word 

; аб = not used | d6 = insideLoop count (current bit) 
; ӘТ = not used | d = rowBytes of dest bitMap 


ЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


x x 
*  Stert actual rotation of bitMaps * 
x x 
3X X ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ KAKA KAKA AAA ЖЖ ЖЖ AKA ЖЖ 
Assumptions: 


height of destination bitMap = rowBytes of srcMap 
Get the baseAddr for our locals into að - this will 
make our program much more readable as we will let 
the assembler do all the addr location calcs for us. 
The addresses will be a fixed number while the 
programs is Clocked down) and running, therefore, 
there is no runtime penalty for doing this addr 
calculation 


"c <. We We We We `. We We We We We We We `. 


lea localVars, ad 
; initialize 40 to contain the pointer to the srcMap 
move.w rowbytes(al),d@ ; get rowbytes of srcMap 


; get regs pointing to bits 


move.] (al),al ; al pts to BITS of src bitMap 
move.1 (a2),a3 ; 83 pts to BITS of dest bitMap 
compute Ini tLowerLef t 
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д 
; compute the lower left corner of the destMap - this maps to 
; the upper left corner of the srcMep end will be used es Базе 
; from which to offset into the dest map when we need to set 
; 8 bit 
7 
сіг.1 41 
move.w 90,91 


с1еаг 41 
load rowBytes of srcMap 
(rowBytes of srcMap = ht of destMap) 


we We We We We 


151." 43,41 multiply by 8, get ht of дес (Мар 
nulu.w 47,01 multiply by rowbytesCdestMap) = fiwords 
sub.w (7,01 ; in destMap less one row 


899.1 а3,91 ; add computed offset to baseAddr of destMap 
поуе.1 di, lowerLeft-localVars(a®) ; init lowerLeft 


д 

д 

; ай = baseAddr for our locals | 90 = rowbytes of srcMap 

; 81 = points to bits of src bitMap | 91 = SCRATCH 

; 82 = SCRATCH | 92 = colmCounter 

; 83 = dest bits | 93 = current srcMap word 
; 84 = SCRATCH | 94 = colmBitLoop counter 
; 85 = not used | 95 = current word destMap 
; 86 = not used | 96 = insideLoop count 

; ат = not used | 97 = rowBytes of dest bitMap 
7 

М 

; -Debugger; 


; init wordCount to zero 


move .w 80 wordCount- localVersCa) 
; set wordCount to one before we start 


д 
; init colmLoop counter 
move.w d7,d2 ; get rowBytes(dest) 
Isr %1,d2 ; divide by 2 - 42 now contains outer counter 
move.w d2,colmCount- localVarsCa£) 
; put the mex value анау for reference 
moveq.] "0,92 ; Set d2 to zero, use it for counter 
colmLoop 
; this is the outside loop 


move .w 815,04 ; init colmBitLoop counter to 15 
move.1 lowerLeft-localVars(a®), currentWord-localVars(ad ) 
; init currentWord 


colmBitLoop 


this is the loop that does the bit counting in the destMap - 
; it is really a misuse of the ‘дога’ instruction since it is 

; not en independent loop but it is a quite cheap method of 

; doing our counting 
: 


owLoop 

loop across each row in the 5гсМар end keep count each time 
we do а row this 'rowCount^ will used to compute the offset 
from ‘lowerLeft’ 


we We We C = Bw 


move.w(al),d3 ; get a word to rotate into d3 
addq.w #2, wordCount- loca lVars(ad) 
; add 1 for each word 000jdoooo 
поуед.1 X *2,d6 ; clear 46 
move.w 815,06 ; initialize inside (bit) loop counter 


innerLoop 
; we will test each bit (15-90 ie. 1t to rt) if it is set then 
; we worry about going out and setting it іп destMap otherwise 
; we just increment the counters and test the next bit 
; (cause we ; cleared them all at init) 
д 

btst 96,93 ; test bit pointed to in the current src word 

; by the inner (bit) loop counter 
beq NoBitToChange 
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; if bits not set skip to next, we cleared 
; them at init of bitMap else set 

; the corresponding bit before we bump the 
; counter to the next bit 


2 
; bit needs to be set - get the word from memoru, set bit and 
; put it back this is veru time consuming аз each word is 
moved 
; in/out of memoru 16 times and a good place to look at for 
; optimization - it probablu means a complete 
; rethink of the жау we are doing this now 

nop 

movea.1 currentWord-localVars(a0),a2 

; get addr of currentWord 
move.w (а2),45 ; get currentWord 
bset 44,05 ; Set proper bit in currentWord 
move.w d5,(a2) ; put the currentWord word back 
; into destMap (memory pt’d to by a3) 


nop 
noBitToChange 


bit was cleared at init of bitMap so we come here to 
increment the counters - we need to move over 1 bit in the 
srcWord and up 1 row in our destMap (which is always 
subtracting rowBytes 


we We We We We DW 


sub.1 dl,currentWord-localVarsCa?) 
; subtract rowBytes(destMap) from current word 


дога d6,innerLoop ; keep looping (thru bits) till 96 = -1 
addq.1 #2,a1 

; point to next word in srcMep - will take 

; us all the way thru the srcMap аз simple es that ! 

; Its the destMap that requires all the dang loops 

; to get the addr of the corresponding word in the 

; destMap 


doneWithSrcWord 


at this point we’ve just completed a word from the srcMap 
| cmp — wordCount-localVarsCa2),d0 
; стр wordCount to rowBytes-are we done with а гон ? 

bne гомоор  ; по - do another word 


doneWithRow 

we just completed а row so add 2 to the count 
move.w #9, wordCount- loca lVars(ad ) 

; 000)00000 reset wordCount to zero 


; following use of dbra keeps track of our destMap bit for us 


поуе.1 lowerLef t-localVars(a@), currentWord-localVars(a) 

; re-init currentWord 

; set the currentWord to the lowerLeft(current) 

; lowerLeft is moved over (right) by а word each 

; time we do а row in the srcMap 

dbra  d4,colmBitLoop ; go thru the bits (15-20) in the 
; destMap - then exit end do it 
; again for rowBytes/2 times 


doneW i thDestWord 


were done counting thru the bits of а destMap word - 

at this point we have 

ectually finished а column in the destMap. The column 
is a multiple of 

16 bits wide (and being at least 1 colm) and es tall 

as the destMap is 

(which is also equal to rowBytes of the srcMap) 


w. `. We We We We We % 
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addq.] #2, lowerLeft-localVarsCa2) 
; this moves us into the next 
; ‘column’ of bits in the destMap 
addq.w 81,042 ; add 1 to the colmLoop counter 
cmp — colmCount-localVarsCa0),d2 ; ere we done yet ? 
bne — colmLoop ; no - do it again 
; else we're done 
7 
; were done so lets do our clean-up/restore 
; and go away gracefully 


CleanUpT ime ; clean-up and get outta dodge 
movem. 1 (sp)+,d3-d7/a2-a5 ; restore registers 
илік аб ; Clean up stack frame 
поуе.1 (sp)+,a@ ; return address 
809.1 %88 sp ; рор parameters off stack 
jmp (ай) ; bye y'all! 


) 
; Set up our data storage area 


localVars ; the beginning of our local var storage area 
colmCount ds.w 1 
currentWord 95.1 1 
lowerLef t 05.1 1 
wordCount ds.w 1 


ENDP 
END 


Listing З rot4Edit 
oe rot4Edit; 


0000000000000000000000000000000000 
rot4Edit by John D. Olsen 
idea by Scott Boyd, Greg Marriott 
and John Olsen 
for 
MacTutor Magazine 
€ Jan 1988 
0000000000000000000000000000000000 


uses 
($LOAD pinterfaces. dump) 
MemTypes, QuickDraw, OsIntf ,PasLibIntf, 
ToolIntf ,PackIntf, IntEnv, CursorCt]; 
type 
integerPtr = ^INTEGER; 
var 
item: Handle; 
itemHit, invertItem : INTEGER; 
mepl, map2, map3, map4 : bitMap; 
rect], rect2, rect3, rect4 : rect; 


FUNCTION NewPtrClear( theSize: size ) : Ptr; EXTERNAL; 
PROCEDURE Rotate( srcMap, destMap : BitMap 2; EXTERNAL; 
PROCEDURE NewBitMapClearC VAR theBitMap : BitMap 2; 
BEGIN 
WITH theBitMap, bounds DO 
BEGIN 
rowBytes := ((right - left + 15) DIV 16) * 2; 


baseAddr := NewPtrClear(rowBytes * (bottom - top)); 


IF MemError © noErr then baseAddr := NIL; 
END; 
END; 


FUNCTION filterProcCtheDialog: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER): BOOLEAN; 
CONST 
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EnterKey = $03; 
BackspaceKey = $08; 
TabKey = $09; 
ReturnKey = $00; 
ClearKey = $18; 
DeleteKey = $7F; 


(bits of the event modifiers long word) 
CommandBit = 8; 
VAR 
itemNum: INTEGER; 
kind: INTEGER; 
box: Rect; 
charCode: INTEGER; 
theChar: Char; 
dialog: DialogPtr; 
noteDialog : DialogPtr; 
itemTgpe : integer; 


BEGIN 
filterProc := FALSE; 


CASE theEvent.what OF 
nul lEvent: 
BEGIN (2, 3, 4, 5) 
GetDItemCtheDialog, 2, kind, item, Бох); 
GetDItemCtheDialog, 3, kind, item, rect2); 
GetDItemCtheDialog, 4, kind, item, rect3); 
GetDItemCtheDialog, 5, kind, item, rect4); 
CopyBitsC thePort^.portBits, mapl, box, 
mapl.bounds, srcCopy, п11); 
RoteteC mapi, map2 ); 
Rotate( map2, map3 ); 
Rotate( map3, map4 ); 
CopyBits( map2, thePort^.portBits, map2.bounds, 
rect2, srcCopy, nil); 
CopyBitsC map3, thePort^.portBits, map3.bounds, 
rect3, srcCopy, п11); 
CopyBits€ map4, thePort^.portBits, map4.bounds, 
rect4, srcCopy, п11); 
DisposPtr( map2.baseAddr ); 
DisposPtr( map3.baseAddr ); 
DisposPtr( map4.baseAddr ); 


END; 
keyDown, autoKey: 
BEGIN 
cherCode := BAND(theEvent.message, charCodeMask); 
IF charCode IN [EnterKey) THEN 
BEGI 
itemHit := 1; 


filterProc := true; 
EXITCf ilterProc); 


END; 
IF cherCode IN [ClearKey] THEN 
BEGIN 


IF theEvent.what = keyDown THEN 
DigDelete( theDialog); 
theEvent what := nullEvent; 
EXITCfilterProc) 
END; 
IF BTSTCtheEvent modifiers, CommandBit) THEN 
BEGIN 
theChar := CHR(charCode); 
CASE theChar OF 
'Х’, ’x’: IF theEvent.what = keyDown THEN 
DigCut( theDialog); 
'C^,'c': IF theEvent what = keyDown THEN 
DigCopy( theDialog); 
‘V’,’v’: IF theEvent.what = keyDown THEN 
DigPaste(theDialog); 
OTHERWISE ; 
END; 
theEvent what := nullEvent; 
EXITCfilterProc); 
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END; enabled, 


END; 
END; /* (4) */ 
(152, 165, 296, 309), 
PROCEDURE EditThatSucker ; EditText ( 
pe enabled, 
strHandle = “strPtr; aia: 
strPtr - ^Str255; ); 
var /* [5] */ 
noteDialog : DialogPtr; (152, 16, 296, 160), 
itemType : integer; EditText ( 
item : handle; enabled, 
box : rect; d 
BEGIN ) 
(Bring up the window) ) 
noteDialog := GetNewDialogC 1000, NIL, windowPtr(-1) 2; ); 
showWindowCnoteDialog); 
SetPort(noteDialog), resource “0100” (1000, “Rotated Text Dialog”) ( 
getDItem(noteDialog, 2, itemType, item, box); (41, 16, 341, 372), 
mapl.bounds :- box; documentProc, 
NewBitMapClear( тәр! ); visible, 
InitCursor; noGoAway, 
repeat 0x0, 
ModalDialog(@filterProc, itemHit); 32723, 
until itemHit = 1; “Rotated TextEdit” 
DisposDialog(noteDialog); ); 
END; (EditThatSucker) resource ‘BNDL’ (128) ( 
^xRot^, 
BEGIN (nain) 0, 
InitGraf CéthePor t); ( /% array TypeArray: 2 elements */ 
BEGIN /* (1) */ 
InitFonts; ‘FREF’, 
InitWindows; ( /* array IDArray: 1 elements */ 
InitMenus; /* [1] */ 
TEInit; 0, 128 
InitDialogs(nil); ), 
END; /* [2] */ 
invertItem := 1; 'ICN82, 
EditThatSucker; ( /* array IDArray: ! elements */ 
END. /* [1) */ 
0, 128 
Listing 4 Resource File for rot4Edit ) 
®include “Турев.г” 
resource ‘FREF’ (128) ( 
{уре 'xRot^ аз 'STR '; ‘APPL’, 
0, 
resource ‘xRot’ (Ø) ( aid 
“Sample Rotation Application - Version 1.0 by John D. }; 
Olsen,RPS of Double Centre Surveying" 
i resource “ІСМ8” (128) { 
{ /* array: 2 elements */ 
/* [1] */ 
resource 'DITL^ (32723) ( $^FFFF FFFF 8000 8001 A400 8070 АА00 8001" 
{ /* array DITLarray: 5 elements */ $"AE00 8039 АА00 8015 А000 8039 8000 8001" 
/* [1] */ %”8000 8001 8000 8001 8000 8001 8000 8001" 
(140, 326, 160, 354), $^8000 8001 8000 8001 8000 8001 8000 8001" 
Button ( $"FFFF FFFF 8000 8001 8000 8001 8000 8001" 
enabled, $^8000 8001 8000 8001 8000 8001 8000 8001" 
“Ок” %%8000 8001 9С00 8005 А800 8055 9С00 8075" 
), $^8000 8055 ВЕ00 8025 8000 8001 FFFF ҒҒҒҒ”, 
/* [2] */ [* 121 */ 
(3, 16, 147, 160), $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
EditText ( $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
enabled, $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
“What do you think about this.. certainly covers" $^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
“all the angles of rotated text don't you th" $“ FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
“ink ?^ $^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
}, $^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
/* [3] */ $^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” = 
(3, 165, 147, 309), ) бэ! 
EditText ( }; Е, 
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QuickTrap Routines Bypass Trap Dispatcher 


Bypassing the ROM trap dispatcher 


In an article a while back, I covered the basics of bypassing 
the Macintosh trap dispatcher to call ROM routines directly, to 
speed up calls to the Toolbox and OS. In this article, ГЇЇ present 
a set of subroutines which implement this technique in a practical 
way. 

The package is written in MPW assembler, and should be 
easily callable from any of the MPW languages. It’s short and 
should be portable to other development systems. It also includes 
a"fail-soft" feature, in case it turns out not to work on some future 
Macintosh. 

A quick review 

Programs call the Macintosh Toolbox and Operating Sys- 
tem routines by executing “illegal” instructions, which are 
handed to the trap dispatching code in the ROM. In addition to 
the time it takes for the 680x0 processor to recover from the 
emotional trauma of this illegal instruction, the dispatcher must 
fetch the offending instruction, decode it, and call the routine it 
specifies. This is very general, since it “hides” ROM locations 
from the application, but it’s also slow. 

With the GetTrapAddress routine, you can calculate the 
address of a ROM routine just once each time your application 
runs. Calling that address directly can save you a lot of time, with 
very little cost in generality. 

What does the dispatcher do? 

Here’s the code for the dispatcher in my MacPlus ROM. 
Your Mac may have something a little different, but all existing 
Macs seem to be similar in principle. The dispatcher, at address 
$401F52 in my ROM, disassembles to: 


disp: 
SUBQ.L 82, SP ; edd 2 bytes above CCR 
MOVEM.L 01-02/А2, -CSP) ; save 12 bytes of regs 
MOVE.L 12+4С5Р), A2 ; get PC of (гар word 
MOVE .W СА2)+, 02 ; get A-trap word 
MOVE .L А2, 12*4CSP) , restore updated PC 
MOVE .W 02, 01 ; сору trep word to 01 
ANDI.W ¥8$Q1FF, 02 ; get just trap number 
CMPI.W "$4800, 01 ; (гар or 0$? 
BLO.S 900$ ; jump if OS 
LEA $0000, А2 ; point Toolbox dispatch 
LSL .W "2, D2 ; Scale number-> longwords 
MOVE.L (A2,D2.W), 12(SP)  ; copy address to stack 
CMPI.W "$ACOD, 01 ‚ "euto-pop^ bit set? 
MOVEM.L — (SPO*, D1-D2/A2 ; restore regs; leave CCR 
BLO.S callTB ; Skip if "auto-pop^ off 
MOVE.L ($Р)+, (SP) ; RIS to caller, not glue 
tBox: RTS ; *call^ Toolbox routine 
4005: 
(ҒА $0400, А2 ; point to 05 dispatch 
BCLR 88, 02 ; Clearktest "keep AQ” bit 
BNE .S 05а0 ; Skip to allow Аб returned 
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LSL .W #2, 02 ; Scale number-?longwords 
MOVE.L (А2,02.\), А2; fetch 05 routine address 
MOVEM.L Ай-А1, -CSP) ; save regs Cincl AQ).. 
JSR (А2) ; «call 05 routine.. 
MOVEM.L (SP)+, АЙ-А1 ; „and restore 05 regs 
OSrt: 
MOVEM.L (SP)+, 01-02/А2; restore OUR regs 
ADDQ.W "4, SP ; ignore stacked CCR 
TST.W 00 ; preset CCR on result 
RTS ; and return 
05а0: 
ЕСЕЙ | #2, 02 ; Scale number-> longwords 
MOVE.L (А2,02.М), А2; fetch OS routine address 
MOVE.L A1, -(SP) ; preserve A1, *not* А0.. 
JSR (А2) .call 0$ routine.. 
MOVE.L (SP)+, Al ; «and restore А1 
BRA.S OSrt ; Clean up with common code 


[Anaside: This is the first piece of ROM code I everread, and 
I still think it’s a great example of tight 68000 coding. It's ti ghter 
on the Mac II, with indirect addressing available. I can’t see any 
way to make it faster; can anyone spot a way to save a few bytes, 
though?] 

Besides figuring out which routine to call (using the Toolbox 
dispatch table at $0C00 or OS table at $0400), the dispatcher also 
does some other important things. For Toolbox traps, it discards 
the return address if the “ашо-рор” bit is set — this is useful for 
"glue". And for OS traps, it preserves D1, D2, A1 and A2, and 
sometimes А0. For OS traps, it also passes the low nine bits of 
the trap number to the routine, in D1, 

Our task is to make a trap “dispatcher” which does all this, 
butis much faster. Note, for instance, that the new code must still 
pass the trap number in D1.w — I believe this is how some 
routines test for flag bits set in the word. (For instance, 
CmpString has a bit to specify if the comparison is case-sensi- 
tive.) 

Hey, waita minute! Isn'titabadideatoknow how oneROM 
routine (the dispatcher) communicates with all the others? Isn't 
code which depends on this interface likely to fall apart when the 
Мас Ш hits the streets? Well, first of all, it'd be awfully hard for 
Apple to change hundreds of routines. But more importantly, 
there's a way to back out gracefully. Trust me; we'll get to it... 

An application's view of the QuickTrap routines 

The fundamental speedup is to get rid of the dispatcher, and 
have one "quick trap" routine for every real routine you'd like 
fast access to. For instance, if your program does a lot of SetPort 
calls, you can easily create "qtSetPort", which has exactly the 
same interface and does the same thing, only faster. As you might 
guess, each qtxxx routine caches the address for its routine. 

Once, at the beginning of your application, you must call 
qtEval, which "evaluates" each address and stores it. If you don't 
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call it, everything will still work — this is related to the fail-soft 
scheme. 

Other than this, everything works the same as old-style trap 
routines. 

Caching problems 

Imagine that you spend a lot of time doing FrameOval calls 
to draw circles on the screen, and would like to speed this up. 
(Actually, I'm sure the trap time is insignificant compared to the 
drawing time; this is just an example.) You install "qtFra- 
meOval" and call it instead everything works great. 

Now your friend gives you this neat, public-domain desk 
accessory which causes all ovals to be drawn on your screen with 
smile-faces in them. [Any takers to write this, by the way? You 
could call it The Smiling Moose...] It does this by altering the 
FrameOval trap to call it. But since your application never 
executes that trap, its ovals are drawn unmolested. How can you 
make sure your ovals are happy? 

The answer is to call qtEval at the right times — not just at 
initialization but whenever you suspect someone has installed a 
replacement trap routine. Since the qtxxx routines are supposed 
to “cache” the real addresses, they must track new address when 
they're installed, or the cache becomes “stale”. 

One way to do this is to call qtEval every time you regain 
control from a desk accessory, each time you regain control from 
Switcher or Multifinder, and each time you invoke an FKEY. 
Perhaps you’dalso have tocall it for every SystemTask call. And 
of course you must call it if your application does any SetTrapAd- 
dress calls for the relevant traps. In short, whenever anyone could 
have changed trap addresses, refresh the cache. 

A simpler approach is to change the SetTrapAddress trap by 
installing a prefix routine which sets a flag in your globals that re- 
evaluation is needed. If DAs, FKEYs, etc., play by the rules and 
use SetTrapAddress calls, nobody can make the trap tables get 
out of sync with your cached addresses. 

It’s tempting to call qtEval in your idle-loop as a heavy- 
handed way to make sure it’s done often enough. I suspect this 
is a bad idea — it can cause seemingly random bugs. 

One other way: if you use, for instance, qtFrameOval only in 
some code which doesn’t relinquish control, call qtEval once 
before each time youenter thatcode. Remember that qtEval isn’t 
all that speedy — it must call GetTrapAddress for every ххх 
routine. 

Reasons not to use these routines 

Because the routines are JSR’d to, they take up four bytes 
instead of two. This is no big problem for most applications, but 
don’t change all your calls. 

When you're debugging, commands to break on traps don't 
work, since your application is not executing trap instructions. 
You can force these traps to occur by disabling the caching; see 
below for details. 

The routines use impure code. You must make sure you put 
them in a segment which is locked in memory. 

Which traps should you replace? 

Remember that many traps take so much time that the 
dispatch isn’t worth improving. Others do next to nothing, and 
speed up a lot. In early use of these routines at Lotus, we 
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estimated about thirty routines were worth replacing. In the OS 
world, things like BlockMove and UprString were included. 
Routines which just twiddled handles are also important, like 
HLock, HUnlock, HPurge, HNoPurge, and GetHandleSize. 
Among the Toolbox routines, things like MoveTo and SetPort 
seemed to help. 

Even if a routine is slow, it may be worth tweaking if it’s 
called a lot. We got measureable improvements substituting for 
CharWidth, DrawString, String Width, and System Task. 

You can also replace package calls, which is kind of a pain. 
If you want to change all the FP68K traps to qtFP68K, you have 
to change Apple’s include files, since each of the SANE macros 
invokes the trap. Another solution is to just redefine FP68K to 
be a macro to JSR to the qtxxx routine. But then you huve to 
define a trap like *myFP68K" which still expands to the A-line 
trap — this is because the qtxxx routine must have a copy of the 
trap word. 

How much does it help? 

Asthe TV diet ads say, results vary directly with how closely 
you stick to the plan. Average performance in a large Macintosh 
product at Lotus was improved by about 5%. A couple of heavily 
CPU-bound loops were improved by 15%. These aren't huge 
gains, but considering that they took only a day or so of work to 
install in a very large program, they're pretty good. 

When does the warranty run out? 

OK,it'stimeto face the music. If these routines dive directly 
into the ROM, they may someday dive into ROM routines in a 
new machine which expect different parameters. (For more on 
this topic, see Macintosh Technical Note #110.) Or even if the 
ROM doesn't change, some caching problem may come up if 
your application's users use some odd way of altering trap 
addresses and making your cache stale. 

The initialization routine qtEval can be easily disabled by 
modifying resources. For instance, when a user calls to complain 
that some FKEY or DA doesn't work with your application, you 
can quickly change a copy of the application to disable address 
caching and test if that's the problem. If itis the problem, you сап 
either distribute the altered application or tell power users how to 
edit the resources to alter the copy they already have. 

The resource used to control caching is QTRP 257. The 
format is simple: if the resource is present and the first word is 
zero, caching is enabled. To turn off caching, just remove this 
resource under Resedit (or renumber it, to easily restore caching). 
Remember that programmers may want to disable caching for 
certain types of debugging when they want to "see" traps under 
a debugger. 

In a future format, a non-zero first word could signal that the 
resource contains a list of specific traps to be enabled/disabled. 

In short, it's easy to experimentally turn off this hackery to 
check if it’s causing problems, and easy to turn it off permanently 
if itis. In tests at Lotus, an application with caching disabled ran 
less than 196 slower than one which executed traps in the first 
place. This is the cost of calling a qtxxx routine, which in turn 
must do the xxx trap anyway because caching is off. 

Notes on the code 
The routines are intended to be pretty simple; I'll walk 
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through them and point ош a few things. 

Code caching: While this stuff works fine on a Mac II, I 
believe it ought to flush the 68020's code cache after patching 
itself. Any recommendations from 68020 gurus out there? 

Layout: The Toolbox and OS routines are laid out with 
symbols defining offsets in them. This is so they can be patched; 
the symbols must stay in sync with the layout. 

Toolbox routines: These start out looking a lot like “glue” 
routines for a higher-level language — they use the “ашо-рор” 
bit, so their return is ignored and the trap returns straight to the 
application routine which called qtxxx. This trap word, plus four 
bytes of slop, is patched to be JMP «trap address». Also, before 
the entry point there's another copy of the trap word, in case 
qtEval is called more than once. 

OS routines: These are more complicated. In their simple 
form, they execute the trap and return, because there is no “ашо- 
pop" bit for OS calls. After being patched, they do just what the 
dispatcher does: save registers, set up D1 and D2 with the trap 
number, JSR to the routine, restore registers, test DO.w, and 
return. Note that the registers saved and restored depend on the 
trap word — if bit 8 is set, then AO is included in the registers 
saved. 

Bit-coding: The OS routines hard-wire the trap number 
passed іп D1 and D2. И you want to call, for example, 
NewHandle with the “clear” bit set, you must define two rou- 
tines: qiNewHandle and qtNewHandleClear (or whatever you 
want to call them). This is necessary because your JSR 
qtNewHandlecan'tcommunicate whether it wants the “clear” bit 
set — that's something normally encoded in the trap word. 

Adding routines: The qtTool and qtOS macros do all the 
Work for you. For each one, supply the name of the qtxxx routine 
you want to define and the ххх name of the trap it's going to 
handle. 

Using the routines 

Pick some segment which won't leave memory and change 
the "SEG" directive to specify it. 

Assemble the routines and link them into your program as 
normal. If you're using a higher-level language, declare the ххх 
routines to have exactly the same calling interface as the xxx 
trap, except that they're defined externally instead of invoking 
in-line trap words. 

Remember to call qtEval once at startup. And if you want to 
avoid the cache getting stale, use one of the strategies described 
above to decide when to call qtEval again. 

If you're using a language which uses glue, you may not be 
able to easily do this. Write to your language developer and 
pester them to do it for you... 

Comments? Improvements? Letter bombs? 

Га be interested to know how these routines work, how easy 
they are to install in various development environments, and 
what kind of performance improvements you see from using 
them. Drop me a line at P.O. Box 11378, Honolulu, HI 96828. 

Since this stuff is stretching the ROM in ways it wasn't 
meant to be stretched, I'd also appreciate hearing about the 
technique in general. Do you think it's safe? Can you suggest a 
better way? And if you have improvements, send them in to 


O The Definitive MacTutor, Vol. 4 


MacTutor... 


; Macintosh Toolbox and 0S-trap bypass routines. 
; Copyright € 1987 Michael S. Morton 


: History: 10-Мау-87 - ММ - Initial version. 
; 22-0ct-87 - MM - Neatened for publication. 


BLANKS ON 

STRING ASIS 

PRINT OFF 

LOAD ‘tlAsmSyms.sym’ 
PRINT ON 


; Impure code! Should be in a segment which is locked in memory. 
SEG 'LOCKDSEG^ ; *** change to а locked segment *** 


Each Toolbox routine starts out life as: 


f 2 «риге copy of trap word? 
; entry: 2 «(ғар word with auto-pop bit? 
j 4 «four bytes unused? 


; The evaluator changes this to: 
; 2 «pure copy of trap word? 
; entry: 6 М <actual address) 

; Either form is callable with a JSR because the former 

; includes the “auto-pop” bit, so the Toolbox routine returns 
; to its caller’s caller. Offsets are: 


tTrap: EQU 0 ; pure copy of trap 
tJump: EQU 2 ; УМР xxx.L instruction 
tAddress: EQU 4 ; address to jump to 
tLength: EQU8 ; length of one block 


; Тһе “qtTool” macro generates code for one “qt” Toolbox routine. 
; args: routine - Name for routine. 

Р Typically “qt? plus trap name. 

I trap - Name of the trap, eg, “-МоуеТо”. 


MACRO 
qtToo] 
EXPORT &Suslst[1]; define the "qtXXX^ routine globally 


&Syslst[2] ; first, a pure copy of the trap word 
&Syslst[1]&Syslst[2] autoPop 
, entry: if not overwritten, just trap 
ds.b 4 , reserve room for overwriting 
ENDM 


Each OS trep bypass routine is 28 bytes long. 
The unevaluated routine is: 
2 «pure copy of trap word? 
entry: 2 «trap word) 
2 RTS 
4 MOVE.W 8000, 01 


only this part.. 
.gets executed before eval 
trep word patched here 
4 MOVE.W 86000, 02 trep number patched here 
6 JSR xxx.L routine address patched here 
4 MOVEM.L (SP)+, 01-02/А1-А2; register list patched here 
2 TST.W DØ ; Set condition codes 
2 RTS ; and return 
After the evaluator is done, the routine becomes: 
2 «pure copy of trap word? 
entry: 4 MOVEM.L D1-D2/A1-A2, -CSP) ; (saves Аб too, 
; if bit 8 set) 
4 MOVE.W #<“trapword,, 01 ; get trap word in 01 
4 MOVE.W #<{гармога & $01FF>, D2 ; „апа trap number 
6 JSR xxx.L ; call the routine 
4 MOVEM.L (SP)+, D1-D2/A1-A2 ; (gets Ай too, if bit 8 set) 


we "e. "e We We We We We We We We We We We Be 
we We Ve We We 


Wwe We We We We Be 


2 TST.N 00 ; Set condition codes 
2 RTS ; &nd return 

оТгар: EQU 0 ; original trap word 

oSave: EQU2 ; for MOVEM.L xxx, -CSP) to go 


oTrapWord: EQU 8 ; for trap word in MOVE.W Зххх, 01 
oTrepNum: EQU 12 ; for trap number in MOVE.W #xxx, D2 
oAddress: EQU 16 ; address to jump to 
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oRestore: EQU 22 ; for second copy of MOVEM regs list 


oLength: EQU28 ; length of one block 
; The “4405” macro generates code for one “qt? 0$ routine. 
; ergs: routine - Name for trep routine. 
: Typically “qt” plus trap name. 
; {гар - Name of the trap, eg, *-GetHandleSize". 
MACRO 
4105 
EXPORT &Syslst[1]; define the *"qtXXX^ routine globally 
&Syslst[2] ; pure copy of trap word 
: &Syslst[ 1)&Syslst [2] 
; entry: if not overwritten, just trap.. 
RTS ; .&nd return 


MOVE .W $5555, 01; get trap word іп 01, Гог 0$ routine 
MOVE .W 8%5555, 02; and ігар number 
JSR 455555555 ; leave space for 8 longword address 
MOVEM.L СР +, D1-D2/A1-A2 

; assume Аб not in the register list 


TST.W DØ ; set condition codes 
RTS ; and return 
ENDM 


; Resource type and ID for the flag used to disable the trickery. 


qtrpType: EQU 'QTRP' 


; resource type for flag 
qtrpld: EQU257 


; resource ID for flag 


 qt£vel 


д 

; description: 

; Updete the routines so they jump directly into 

; the ROM, or wherever. This routine should be called 

; at startup, end each time the application 

; thinks anyone has Cor might have) called SetTrepAddress. 


; uses: (по registers) 

qtEval: PROC EXPORT 

; Stuff used in patching together routines: 

jmpInst: EQU$4EF9 ; opcode word of JMP ххх. 
OSregs: REG 01-02/А1-А2 ; registers saved by 0S dispatcher 
OSregs2:REG 01-02/А0-А2 ; registers saved when bit 8 is zero 


MOVEM.L 00-02/А0-А2, -(SP) ; save caller's registers 
; First, see if we’ve already been told not to do our thing: 
LEAqtEnabled, A2 ; point to the flag 
TST.B (А2) ; have we snuffed it already? 
BEQ evelEnd ; yes: nothing to do 
; Second, decide if the resource flag allows us to map/cache. 


SUBQ "4, SP : make room for function result 
MOVE. L чаќгрТуре, -(SP) ; pass the type.. 

MOVE .W *qtrpId, -CSP) „and ID 

Ge tResource try to find our flag 

MOVE.L (ӨР), Аб рор result.. 

MOVE.L Аб, 00 „and test for NIL 


BEQ.S evelTurnOff 
MOVE.L (Ай), А! 
MOVE.W CA1), 02 
МОХЕ 1 AG, ~(SP) 
-ReleaseResource 
TST. D2 

BNE.S: evallurn0f f 


no such thing? go flag this and exit 
deref . handle; point to rsrc with АВ 
pick up first word, to check later 
pass handle.. 

„and get rid of it 

now check - did rsrc start with zero? 
; „ло: we don’t yet do selective disable 


mee We We We Be We We %. We We We ә 


; Nothing forbids hackery. 
toolbox bypass routines. 


LEA qtToolStart, Al ; point to first routine 

LEA qtToolEnd, А2 ; point to just efter last routine 
MOVE.W *jepInst, 01 ; get a UMP xxx.L instruction 
BRA.S toolEnd ie ; check for no routines 


Evaluate all the 
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toolLp: MOVE.W Игар(А!), 00; pick up the trap number in DØ.w 
GetTrapAddress newTool ; ask where this routine lives 
MOVE.L Аб, tAddress(A1) ; store address first, THEN. 
MOVE.W 01, tJumpCA1) ; «=the JMP, so routine’s always OK 
А000  "tLength, Al ; advance to the next routine 


toolEnd:CMP.L A2, А1 
BLO.S toollp 


; at Cor past) end of toolbox routines? 
; nope: go evaluate another one 


; Evaluate all the 0S bypass routines. 

LEA qtOSStert, A1 ; point to first.. 

LEA qtOSEnd, А2 ; „апа to just after last 

BRA.S osEnd ; handle degenerate case 
osLoop: MOVE.W oTrapCAl), 00; pick up trap number 
MOVE.W DØ, 02 ; copy it for later use (BTST, etc.) 
-GetTrepAddress new0S ; find where the routine lives 
MOVE.L Ай, оАддгеѕѕ(А1) ; save routine address in JMP xxx.L 


MOVE.W 02, oTrepWordCA125; fill in MOVE.W #trapword, 01 
AND.W #$@1FF, 02 ; get just the {гар number 
MOVE.W 02, оТгарМим(А1) ; and store in MOVE.W #trapnum, 02 


; Decide whether the saved registers include А0. 

MOVE.L OSent, 00 ; essume we want usual registers saved. 

MOVE.L OSexit, D1  ; „апа restored 

BTST #8, 02 ; but should we save Аб, too? 

BNE.S osLpi ; hope: OSent’s registers are fine 

MOVE.L OSent2, DØ =; yep: use reg list which includes Ad 

MOVE.L OSexit2, 01 ; .end ditto for one which saves Аб 
osLp1: MOVE.W 01, oRestoreCAl) ; store register list for restore 

MOVE.L DØ, обауе(А1) ; lastly, get rid of ist trap 

ADD "oLength, А1 ; advance to the next routine 


osEnd: CMP.L A2, A1 
BLO.S osLoop 


; at the end? 
; hope: go do another 


evalEnd:MOVEM.L СР +, 00-02/А0-А2; restore caller's registers 
RTS 


; Here when the resource forbids caching. 
; А2 points to the flag. 
evalTurnOf f : 
SF (A2) ; «disable it for faster call next time 
BRA.S evalEnd ; Clean up end exit 
; *** [mpure *** flag: 0 means mapping disabled; non-zero means 
enabled. 
qtEnabled: 
DC.B  $FF,00 ; initially enabled; 2nd byte to align 
; Instructions end register lists to stick into 05 routines. 
Eech is 2 words. 
OSent: MOVEM.L OSregs, -CSP) 
OSent2: — MOVEM.L OSregs2, -CSP) 
OSexit: MOVEM.L ($Р)+, OSregs 
OSexit2:MOVEM.L ($Р)+, OSregs2 
; Toolbox trap replacement routines. To be re-evaluated, 
; these must be between qtToolStart and qtToolEnd. 
; Nothing else must be in here - the evaluator 
; walks through this as an array. 
qtToolStart: ; Beginning of Toolbox trap replacement routines. 
417001 qtMoveTo, _МоуеТо 
417001 qtSetPort, SetPort 
; „ада your own here.. 
qtToolEnd: ; End of Toolbox trap replacement routines. 
; 05 ігар replecement routines. Ав with toolbox, 
; keep only these in here. 
qtOSStert: ; Beginning of 05 trep replacement routines. 
4405  qtHLock, HLock 
4408 — qtHUnlock, HUnlock 
; -add your own here.. - 
; End of 0S trep replacement routines. Sel 


caus 


qtOSEnd: 
END 
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Assembly Language Lab 
FKEY that runs other FKEYs! 


[John Holder is a previous contributor to MacTutor and is 
well known for his numerous FKEY shareware products. In this 
article, John shows us how to create an FKEY that runs other 
FKEYS without installing them in the system folder! Hence this 
FKEY has an event loop, menu bar and all the other goodies 
normally found т aregular application. The source code diskfor 
this month also includes two of his more popular FKEYS to use 
as launch samples, along with a shareware application so you 
can contact John about other goodies he might have for you. -Ed] 


What’s an FKEY? 

FKEY’s (Function Keys) are resources containing execut- 
able code that are called upon by hitting the keys Command- 
Shift-# (any number 0-9) at the same time. In the standard 
System file there are two FKEY's; with an ID#3 and #4 that are 
used to dump the current screen or window onto disk or printer. 

There are also many other FKEY's out in the Mac world, 
some Public Domain or Shareware, and others are sold commer- 
cially. They can be installed into the System file by using 
"ResEdit" ог “Екеу Installer" (this application was created by 
"Dreams of the Phoenix, IncTM” and released into the public 
domain to encourage people to make Fkeys). The Екеу presented 
in this article can be used to access other Fkey's which are not in 
the System file! 


What's this all about? 

This article will show you how to create an FKEY with an 
interface similar to a standard applications (menus with com- 
mand key equivalents, windows, and an event loop). It does not 
support DA’s nor does it have an EDIT menu, but if you need to 
add this function to your own Fkey it would be very simple. 

This Fkey was created with the Macintosh 68000 Develop- 
ment System. АП applications are on a disk titled * MDS1' and 
all .D files are on a disk titled *MDS2'. First assemble the file 
‘FkeyTemp.Asm’, then run the linker on the file 
'FkeyTemp.Link', and finally run RMaker on the file 
'"FkeyTemp.R'. You will now have an FKEY ready to put into 
your System file! 


Fkey Sampler, How it Works 

First, we create an offset table that is used to store the 
FKEY's many "global" variables. This is done by naming the 
offsets that it will need such as sfReply, WindPtr, etc., and 
calculating how many bytes each will take (explained under 
"How to set up the offset Table"). 

When the Fkey starts, there is a short jump over its header, 
then the applications current port and all registers are saved, next 
it brings up the standard arrow cursor with InitCursor. We now 
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Авт Link 


Open FKEV ЗЕЕ 


Fig. 1 Our FKEY launches other fkeys! 


check the global variable MenuList to see if the application 
which iscurrently running has a menu, if it doesn't have one (like 
the MiniFinder) then we can't let the Fkey run! If it does have a 
menu, we try to allocate enough space for the Fkey's global 
variables by making а non-relocatable block with NewPtr. If 
there is not enough memory for the globals (there has been an 
error if _NewPt returns azero in register AO) it beeps the speaker 
and returns to the Application. Otherwise, a pointer to the storage 
area is put into register А4. 

If the storage was allocated, we go on and get a handle toa 
copy of the applications menu bar with GetMenuBar, and clear 
the menu so that we may replace it with our own. After the Fkey’s 
menus are created with_NewMenu,_AppendMenu, and_Insert- 
Menu, we create a window that will simulate the standard 
desktop. Creating a new window generates an update event, so 
when it gets to the main event loop, the window will be filled with 
the current desktop pattern. 


The Main Event 
Now its off to the main loop to look for events. This Fkey 
uses only keydown, mousedown & update events. Upon a 
useable event we jump to the appropriate routine to handle it, if 
it’s an update event the background window is filled with the 
Current desktop pattern (found in the system global variable 


Мате Commend Key # 


$&&-Shift-3 
8&-Shift-4 


Rpple Screen Capture (BU) 
Rpple Screen Capture (ВШ) 


Colorimage by Steve Sheets  €-Shift-S 


FkeyUiew 2.5 8&-Shift-? 


Fkey Sampler %-Shift-9 


FKEY Viewer 2.5 © 1986,1987 John Holder 


Fig. 2 A useful FKEY running under our FKEY 
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*DeskPattern"). Other events аге 
handled just like a standard applica- 
tion by using a jump table to jump to 
the appropriate routines. 


Edit FkeyTemp.Asm Asm Fkey Temp Rel 
Doing the About... h 
When the mouse is clicked in E x 
the *About Fkey Sampler..." menu — i 
item under the Apple menu, a win- FkeyTemp.Link T 
dow is created and set as the current 


port. Then the windows text font 
and size is set to 9 point Monaco 
with  TextFont and  TextSize. 
Now the stack is set up for Text- 
Box (a very handy routine that dis- 
plays text in a given rectangle with 
left, right or center justification!) 
Then we jump to a routine that uses 
_GetOSEvent to watch for а 
mousedown or key down event. 
When akey or the mouse button has 
been clicked we dispose of the window, unhighlight the menu 
and return to the main loop to get the next event! 


Opening the Fkey 

The purpose of this particular Fkey is to open and use other 
FKEY’s (of Type ‘FKEY’) that are not in the System file. When 
this routine is called, the standard get file dialog is displayed with 
_Pack3. If a пате is chosen, the volume the file is on is set as the 
current volume with SetVol. Now we try to open the resource 
fork of the file (_OpenResFile will return a #-1 if it can’t open a 
files resource fork). If the resource file opened with no problems 
we want to get the Fkey resource which is inside this file and 
execute it (run it, not kill it!). | 

Now we want to get the first Fkey resource in memory by 
using _GetIndResource (the newly opened res file is searched 
first). We check to make sure the returned Fkey is from the newly 
opened resource file by using _HomeResFile (when given a 
handle to a resource, this routine returns its resource files refer- 
ence number). If it is from the Fkey file just opened, the Fkey 
resource is locked in memory (we don't want the Екеу moving!), 
the handle is made into a pointer and the Fkey is executed by 
jumping to it (with JSR). When that Fkey is done, we close the 
resource file and return for the next event. 


Doing the Quit! 

When an Fkey quits it must dispose of any memory it 
created. The first thing dumped is the window used as the 
desktop, then the menus it made are released from memory with 
_DisposMenu and the menu bar is cleared. Now the applications 
menu bar is restored, the memory we allocated for the globals is 
released, all events are flushed, the applications current port and 
registers are restored, and a return from subroutine RTS returns 
command to the application! 


Making your own FKEY 
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&— i6 — E 


Fkeu Temp.Code 


FkeyTemp.R RMaker 2.2 


Fkey Sampler Fkey 


Fig. 3 Map for how the FKEY is constructed 
Use ResEdit to copy the FKEY into the system file 


АП Екеу” must start with the FKEY header shown in the 
code listing. The only thing you will need to change in the header 
for your own Fkey is the ID number. Youcan use this Fkey to test 
all of your own Fkeys without installing them into the System 
file! 

To make your own Fkey using this one as a template should 
be very simple. Just make your own offset table, or use this one 
and add your own needed offsets (explained below), then add 
your own menus and the appropriate routines to handle them. 
Also, change the contents of the text between MyTextBegin and 
MyTextEnd to whatever you want for your Fkeys ‘About..’ 
window. 

A complete jump table for events and a jump table for where 
the mouse was clicked (returned by FindWindow) is included 
to help in making your own Fkeys. Just remember to always 
check if there is enough memory before loading a resource or 
creating storage and to dispose of any storage that the Fkey 
created before returning control to the application! 


How to set up the Offset Table 
Lets say you need room for one handle (4 bytes) and two 
separate words (2 bytes each) of storage. 
For the this storage you would need to put #8 into register DO 
before calling _NewPtr (8 bytes are needed) 


;Your Offset table Cexemple) 


AHandle equ Ø ;4 bytes 
AWord equ 4 ;2 bytes 
NextWord equ 6  ;2 bytes 


Register A4 points to your global storage area. To store a 
word into the global “AWord” just use: 


move #99, AWord(A4) 
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To put the value contained in AWord(A4) into Register D2 


, USC: 


move AWordCA4), D2 


That’s all folks... 


Well, that’s it, I hope you've learned something, and I hope 
to see lots of new Fkeys around! 


;File: 


FkeyTemp.Asm 


“Ап Fkey sampler Fkeu 
2/8/87 


‚Ву John Holder 
;Revised 


д 


3/29/88 


Include Тгарѕ.р 
Include Toolequ.D 


Include Sysequ.D 


Ee SS 
,Macros to save & restore the registers 


MACRO 
movem. 1 


MACRO 
movem. | 


SaveRegs = 
A®-A4/08-D7,-CSP) 


RestoreRegs = 
(SP )+, АВ-А4 /00-07 


“ATI equates go here 


; these are offsets into the global storage. 
; Са non-relocatable block we created pointed to by А4) 


sfReply equ 
GetVRef equ 
GetVers equ 


GF i leName equ 
IOPeremBlk еди 


WindPtr equ 
EventBlk equ 
what equ 
message equ 
when equ 
where equ 
modify equ 
wW indow equ 


Menu ІНпа1 equ 
Menu2Hnd1 equ 
oldMenuBar equ 


TheWindow equ 


event masks for 
mDownMask equ 
keyDownMask equ 


,Menu equates 

AppleMenu equ 
AboutItem equ 
FileMenu equ 
OpenFkeyItem equ 
QuitItem equ 


192 


,Sfreply record 


;lOperamblock (80 bytes) 
ог our background 
¿window 

¿Event Block 

jEvent number 

¿Additional information 
¿Time event was posted 
¿Mouse coordinates 

jotate of keys and button 
¿Window pointer 

¿handle to our Apple menu 
¿handle to our File menu 
¿handle to applications 
¿menu 

;for _FindWindow 


-GetOSEvent 


2 
8 


1 
1 
2 
1 
3 


¿Apple Menu 


¿File Menu 
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АТТ FKEY's must have this FKEY resource header! 


7 


bra.s StartIt 

dc 0 

dc.b 'FKEY" 

dc 9 

dc 0 
StartIt 

SaveRegs 

Subq #4 SP 

моуе.1  SP,-(SP) 

-GetPort 

-InitCursor 


,does application have a menu??? 


;branch over header 
;flags (not used) 
,resource type 
¿Resource ID 8 
¿version 8 (not used) 


,save regs MACRO 


,save Port for later 
jstandard arrow cursor 


jno menu, Беер & quit! 
‚200 bytes of storage 
Гог our globals 
¿pointer in A4 

jif not zero, ptr is ok! 


¿otherwise Беер 
jand quit 


¿set up our menus 
¿set up background 


; window 


тоуе.1  MenuList,D0 
beq NoMenuJump 
move.] "200,00 
-NewPtr , CLEAR 
томе. 1  A0,A4 
стр. 1 80 А4 
bne.s StorageOk 
NoMenuJump 
bsr Mem_Error 
bra No_Mem 
Storage0k 
bsr Se tUpMenus 
bsr Se tUpWindow 
; 
MainLoop 
-SystemTask 
сіг -(ӨР) 


move 8ФҒҒҒ,-(5Р) 
реа EventB1kCA4) 


-GetNextEvent 

move (5Р2%,02 

beq MainLoop 

move WhatCA4)2,D0 

add 00,00 

move Еуеп(Тар1е(002,00 


jmp EventTableCD2) 


EventTable 
dc MainLoop-EventTable 


dc  MouseDown-EventTable 


dc MainLoop-EventTable 
dc KeyDown-EventTable 
dc MainLoop-EventTable 
dc KeyDown-EventTable 


dc UpDateJump-EventTable 


dc  MainLoop-EventTable 
dc MainLoop-EventTable 
dc MainLoop-EventTable 
dc MainLoop-EventTable 
dc MainLoop-EventTable 


SetUpWindow 
clr.1 -(SP) 
сіг.1 -($Р) 
реа WindowRect 
сіг.1 -(SP) 
move.b  81,-(SP) 
move 8plainDBox, -CSP) 
поме. 1  8-1,-CSP) 
move.b #0, -(5Р) 
с1г.1 -(SP) 
-NewWindow 


¿standard event loop 


,event mask 
,Plece to return results 
¿Look for an event 


,zero if we shouldn't 
,respond 


¿jump to appropriate 
¿routine 


¿null event 
¿mouse down 
¿mouse up 

Кеу down 

Key up 

¿auto key 
¿update event 
;disk event 
¿activate event 
¿abort 

¿network event 
;1/0 driver event 


ог returned pointer 
;let Mac make storage 
¿windows rectangle 
‚по title 

jit is visible 

‚Туре of window 

jin front 

jno close box 

;refcon zero 

¿make window! 


if not, then quit! 
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томе.1 (SP),WindPtr(a4) ;pointer into global 


-SetPort ;set аз the port 
rts 

SetUpMenus 
clr.1 -(SP) ¿get applications menu 
-GetMenuBar ;ber handle for later 
томе.1 (SP)+,oldMenuBar(A4) ;restoration! 


_C learMenuBar ¿clear Apps menu Баг 
¿make all of our menus 
¿the apple menu 

сіг.1 -CSP) 

move 81,-CSP) 

реа AppleSymbol 


-NewMenu 
поуе.1  (SP)*,MenulHndlCA4) 
move.1  MenulHnd1CA4),-Csp) 
pea ‘About Fkey Sampler...’ 
_AppendMenu 
move.1  MenulHndlCA42,-Csp2 
move #2,-(SP) 
-Inser tMenu 

¿the File menu 
сіг.1 -(SP) 
move 82 ,-(SP) 
pea 'File' 
-NewMenu 
тоуе.1  CSPO*,Menu2Hnd1lCA4) 
move.] Menu2Hnd1(A4),-Csp) 
pea ‘Open ҒКЕҮ/Ғ” 
_AppendMenu 
move.] Menu2Hnd1(A4),-Csp) 
pea “(= 
—AppendMenu 
move.1 | Menu2HndlCA42,-Csp) 
pea 'Quit/Q' 
~AppendMenu 
move.1 Menu2Hnd1(A4),-Csp) 
clr -(SP) 
-Inser tMenu 
-DrewMenuBar ;draw the new menu Баг 
rts 

UpDateJump 
bsr UpDateWindow 
bra Ма1п оор 


“This routine keeps our background window (The DeskTop! ) 
;the same pattern as the current standard desktop! 


UpDateW indow 
поуе.1  WindPtrCA42,-CSP) ;оиг background 


;window 


_BeginUpdate ;is kept in WindPtrCA4) 
move.]  WindPtrCA4),-CSP) 

-SetPort 

pea PaintRect ¿the rectangle to paint 


pea DeskPattern  ;global var, contains 


-FillRect ;pattern used for desktop 
move.]  WindPtrCA4),-CSP) 

-EndUpdate 

rts 


“A key down event occured, check if the command key was 
;down, if not, get the next event! 


KeyDown 
move ModifyCA4),D1 
btst #8 D1 ;check command key bit 


beq MainLoop ;zero if command key 
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;is not down! 


сіг.1 -(sp) 

move message*2(A4),-Csp 
-MenuKey 

поуе.1 (sp)+,D4 ¿put 


beq MainLoop 
bra WhatMenu 


тег FF 
;À mousedown event occured, we only check if its in a menu, if 


;not then get the next event! 


MouseDown 
сіг -CSP) 
тоуе. 1 where(A4),-(SP) 


реа TheWindowCA4) 


FindWindow 
move (SP)+, DØ 


add 00,00 
nove Windowlable(D0),D0 
jmp WindowTableCD2) 


) put cher onto stack 


; for _МепуКеу 


result іп 04 


;if zero, no menu equivalent 


‚мога result 

¿where field of 
,event record 
¿returns the window 
;pntr the 


;mouse was clicked in, 


;if it was in one. 


;jump to appropriate 


;routine 


Ме only use InMenu event! 
WindowTable 
dc  MainLoop-WindowTable 
dc InMenu-WindowTable 


j In Desk 
‚Іп Menu Bar 


dc MainLoop-Windowlable ;In System Window 
dc M MainLoop-WindowTeble ; іп Content 

dc  MainLoop-WindowTable ; іп drag 

dc MainLoop-Windowlable ;іп grow 

dc M MainLoop-WindowTeble ;іп go away 


“Тһе mouse was clicked in the menu Баг. 


InMenu 
сіг.1 -(SP) 
move.] иһеге(А4),-(ӨР) 
_MenuSe lect 
move.] (SP)+,D4 


beq MainLoop 


;jump to here after command key 
WhatMenu 
поуе.1 04,06 


Swap D4 
WhichMenuWasIt 
cmp ®App leMenu, D4 
beq InAppleMenu 
стр 8Е1 ]еМепи ‚04 
beq InF i leMenu 
bra MainLoop 
InAppleMenu 
cmp "About Item,D6 
beq DoAbout 
bra MainLoop 
InF i leMenu 


cmp ®OpenFkey! tem,D6 
beq Open_Fkey 

cmp #001 tem, D6 
beq QuitRoutine 

bra Маіпі оор 


“Show the “About Fkey Sampler.. 


DoAbout 
saveregs 


© The Definitive MacTutor, Vol. 4 


¿zero if no item selected 


down event 


06 will now have the 
; item 8 04 will have menu 8 


;is it in the apple menu? 
;if so, go see which item! 
;is it in the File menu? 
¿where else could it be! 
;in the “Apple? menu 

;its in the About... Item! 
;in the *File" menu 

;in the OpenFkey Item? 
;if so go open it! 


;Quit item? 
jif so go quit 


." window 


;save the registers 


clr.1 -(SP) 
clr.1 -CSP) 
pea AboutRect 


томе. 1 %0-С(5Р) 
move.b  81,-(SP) 
move 81,-CSP) 
move.]  8-1,-CSP) 
move.b #@0,-(SP) 


clr.1 - (SP) 

-NewWindow ¿make a window 
move.1 (СР),А2 ¿put pointer into A2 
-SetPort ¿make it the port 
move 8Monaco, - (SP) ¿Use the Monaco Font 
-TextFont 

move 89 -(SP) ¿make it 9 point (size) 
_TextSize 

pea MyTextBegin ;address of “About” Text 


¿calculate how many chars in text for TextBox 
move.|  8MyTextEnd-MyTextBegin, -CSP) 


pea TextRect ;,rectangle for text 
move 81,-CSP) ,center justification 
_Тех{Вох 

bsr WaitForEvent ,wait for button/key down 
move.]  A2,-CSP) 

-DisposWindow ;get rid of the window 
bsr UnHiliteIt 00 unhilight the menu! 
move.]  WindPtr(A4),-Csp) 

-SetPort ¿reset our old port 
restoreregs ¿restore registers 

bra MainLoop 00 get another event 


= —_—а сананы 
¿Wait for mouse ог key down event 


7 
WaitForEvent 
link Аб, t-evtBlkSize j link, event block size 
WaitLoop 
lea -evtBlkSizeCA6),A0 зріс to event block in Аб 
moveq ®#mDownMask !KeyDownMask ,D@ ;Event masks in DØ 
-GetOSEvent 
beq Clicked jif zero, time to leave! 
bra WaitLoop ;loop until event 
Clicked ¿mouse or key clicked! 
unlk Аб ,unlink Аб 
rts 


“Quitting, dispose of 811 our storage and menus and return to 
; the application that the Fkey was called from! 


2 


QuitRoutine 
move.] WindPtr(A4),-(SP) ,dump background 
-DisposWindow ¿window 
move.1  MenulHndl(A42,-CSP) ;dump our #1 
-DisposMenu ¿menu 
поуе.1 Menu2Hnd1(A4),-(SP) ;dump our 82 
-DisposMenu jmenu 
-ClearMenuBar ;clear the menu 
томе.  oldMenuBar(A4), -CSP) 
-SetMenuBar restore apps menu bar! 
move.1  oldMenuBar(A4),A0 ¿dump copy of 
-DisposHandle ,8pps menu handle! 
-DrawMenuBar ¿draw it 
моуе.1  A4,A0 
-DisposPtr ¿dump our global 

¿storage 
No_Mem 


move.] %%0000ҒҒҒҒ,00 ;flush all events 
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-FlushEvents 


_SetPort ,set original port! 

restoreregs ,restore the registers 

rts ¿return to the applica- 
tion! 


Couldn't allocate space for our global storage area 
; just beep & quit! 


7 

Mem Error 
move 819,-CSP) 
—SysBeep 
rts 


_— -- 
;Unhilight menu bar after mouse down in а menu item 


UnHiliteIt 
move 80 ,-(SP) 
-HiliteMenu 
rts 


у гт т 
;беі a file of type "FKEY^, open its resource fork, and 
,execute the Fkey Cif there is one) contained in it! 


Open_Fkey 

saveregs ¿Save registers 

move 882, -CSP) ,coordinates for GetFile 

move 8 100, -CSP) ¿dialog box 

сіг.1 -(SP) ;prompt 

clr.1 -(SP) ;File Filter Proc Pointer 

move 8],-CSP) ¿number of file types 

pea Туре! ist ¿our type list 

clr.1 -CSP) ¿Dialog Hook Proc Pointer 

pea sfReplyCA4) ;Sfreply record 

move 82,-(SP) ‚#2 for SFGetFile 

-Pack3 ;Са11 the Get File Pack 

cmp.b %0 51”Кер1у(А4) 

beq Cancel jif user hit cancel, quit! 

bsr UpDateWindow ¿update window before 
¿opening the Fkey 

lea IOParamBlkCA42,A2 ;the IO param block 

сіг.1 12(А2) ,zero *ioCompletion" 

lea GFileNameCA4),AB ;put a pointer to the files 

move.] АВ, 18CA2) ¿name into “joNamePtr’ 

move GetVRef CA4),22CA2) ;"ioVRefNum^ 

моуе.1  A2,A0 ¿put param block ptr іп Ай 

—SetVol ¿set as current volume 

сіг -CSP) ,Space for refnum 

pea CF ileNameCA4) ,name of res file to open 

-OpenResF ile ;Ореп that resource file 

move (5Р2%,07 ,put result in 07 

стр 8-1,07 ¿will be -1 if ang 
,errors! 

beq Cancel jif error go to cancel 


¿this stops resources from being loaded with GetIndResource, 
;GetResource or GetNamedResource 
move.w — 80,-(sp) 


-SetResLoad 

clr.] -(5р) 

поуе.1 *’FKEY’,-(sp) 

move 81,-Csp) 

-GetIndResource ,get first FKEY resource 
move.] (sp)+,A3 ¿handle into АЗ 


j Turns Automatic resource loading back on! 
move.b &1,-(5р) 
-Se tResLoad 
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clr.1 -(sp) 

move.] A3,-(sp) 
-SizeRsrc 

поуе.1 (sp)+,D2 
стр.1 %-1,02 

beq NotEnoughMem 


;how big is the resource? 


271 = no resource 


¿no resource error so quit 


;do we have enough memory to loed the FKEY 


move.1  D2,D0 


-NewHandle 

move.] А0,А1 

cmp.1 80 А1 

beq NotEnoughMem 

-DisposHandle 

move.]  A3,-Csp) 

-LoadResource 

clr -(sp) 

move.] A3,-(SP) 

-HomeResF ile 

move Csp)+,D2 

cmp 02,07 

beq YepItsFromNewF ile 

bra NotEnoughMem 
YepI tsFromNewF ile 

move.] АЗ,А0 

-Hlock 

поме. САЗ),А2 

SaveRegs 

jsr (A2) 

RestoreRegs 

move.| АЗ,А0 

-HUnlock 


bsr CloseIt 


;жаз zero returned? 


¿not enough room, so quit! 
¿otherwise dispose the new 
;handle, and go on.. 


оаа resource into memory! 


¿what resource file 


;is this resource from? 


;is it from new file? 


жер! 


;if not, close the res 


;file апа quit! 


;Lock it before jumping to it 
;put pointer to FKEY in A2 


¿save the regs 
¿Run the Fkey!! 
¿restore the regs 


;UnLock FKEY handle 
;go close res file 


rts 


:AM constents go here 


*rect of background (desktop) window 
¿make it giant to cover entire background! 


WindowRect dc 0,0,4000,4000 
PaintRect dc 0,0,4000, 4000 
TypeList адс. 'FKEY' 


„ALIGN 2 


;rect of “About...” window 
AboutRect dc 138, 160, 190,412 


;rect text will be displayed in for _Тех{Вох 
TextRect dc 10,10,90,302 


AppleSymbol dc.b1,$14 ;арр1е symbol for menu #1 
ALIGN 2 


MyTextBegin  dc.b 'Fkey Sampler 1.0”,%00,%900 
dc.b “Written by John Но1дег” 
.ALIGN 2 
MyTextEnd 


END 


;The Linker file (file name FkeyTemp.Link) 
1 


FKEYTemp 
^JOutput FkeyTemp . Code 
2 we ^ TEMP! 


Cancel 
restoreregs ¿restore the regs 
bsr UnHiliteIt junhilight the menu 
bra Ma inLoop jget the next event «Тһе RMaker file (file name FkeyTemp.R) 
Екеу Sampler .Fkey 
NotEnoughMem ҒКЕҮ00 15 
bsr CloseIt 
bre Cancel TYPE FKEY = PROC 
Екеу Ѕатр1ег,9 
CloseIt FkeyTemp . Code = 
move D7,-CSP) бэ. 
-CloseResF ile ;Close the res file ID 
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Assembly Language Lab 


Font Dialog Box Using List Manager 


Ray. A. Cameron is an Electrical Engineer from Brunswick, 
Victoria in Australia, employed by Telecom, the Australian 
Telecommunication Commission. He is currently involved in the 
introduction of optical fibre into the Customer Access Network. 
This is his first article for MacTutor. 


MacTutor Down Under 


Before I start writing about my routines l'd like to say how 
fantastic MacTutor is for the service that it is providing to Mac 
programmers in disseminating programming ideas and tech- 
niques. It doesn't matter which language we program in, it is 
possible to gain information from every article published in 
MacTutor. 

Something that Iknow would be beneficial to all readers of 
MacTutor is if the writers of articles include in their description 
not only how the program works (as published) but what prob- 
lems they have encountered along the way or techniques thay 
have employed and why. Also any idiosyncrasies in the system 
software that don't appear to be fully explained in Inside Macin- 
tosh. 

What This Program Does 


The FontDialog routine displays a Modal Dialog box for the 
user to select a font name, size and style. The routine is designed 
to be incorporated into a program, as I have done with the 
*Window" example (distributed with the old MDS software and 
included here), which is on this month's source disk. There are 
tworoutines thatI have written, the first routine (SetupFontMap) 
creates a record of all the “ҒОМТ” resources available to the user 
in the system file. It doesn't look for ‘FOND’ or 'NENT' 
resources or fonts attached to documents. The next routine 
(FontDialog) creates a Modal Dialog box (Fig 1) so that the user 
can choose a font name, size and style. The font name and size 
lists are created with the List Manager from data stored in the 
FontMap record. The routine also includes a UserFilter with the 
Modal Dialog to handle events. 

Some of the procedures and functions used in the FontDia- 
log routine take up a number of lines and аге used often so I’ve 
converted them into Macros to save space. I won't describe the 
Macro file as it should be self explanatory. 


User Interface 
The Dialog box presented in this example is similar to the 
one in Microsoft Word. Now that we can all use nested menus to 


select font, size and style, you might want to be old fashioned and 
go back to a text dialog box instead! You can select a font name 
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Asm Link 


BE Character Font 0 Attributes 


Font Size: 
J 


Spacing 
О Normal 
О Condense 
| © Extend x 
i rA YKL MNOFORSTUV WXYZ 
abcdetghik/mnopgrs ; 
Au SPACEY) 


Cer Ca) 


Style 
О Bold 
Ы italic 


Font Name: 


Palatino 
Symbol 
ThinSaratoga 


New Century Schit 
New York ІШ 


09 Underline 
О Outline 
Г] Shadow 


Fig. 1 Our Font Dialog Box selects text, size & style 


by either clicking on a font name or by typing a character to select 
the first name starting with that character (or the first name to 
follow in alphabetical order). As you continue to type additional 
characters (up to 31) any file that matches the characters you type 
is found and selected. If you pause while typing, the next 
character is considered to be a new request, rather than a continu- 
ation of your first request. The Delay Until Repeat setting which 
you set in the (Control Panel) determines how long you can pause 
before additional characters are considered to be a new request. 
Hence our dialog box is fairly intelligent in that it includes a sort 
and search routine and uses the list manager, useful techniques 
for a variety of dialog functions. 

The Font Size Selection Window displays the sizes that are 
currently available on the system (for the selected font name). If 
no font name is selected then the Font Size Selection Window is 


€ File Edit Font 


Fig. 2 After text selection, our sample text window 
allows typing in the chosen font & style 
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.w | # of different fonts - 1 
1 1 
w ШЕСІ — 


font 
.w | offset to font name eference 
list 


.w | offset to font sizes 
| 


Font 


.b | length of font name (nj font 
name 
b E 


м | # of font sizes (m) font 
size 
mx.w | _ fontsizes | ist 


Format of theFont Map 
Fig. 3 Layout of our custom font map structure 


blank, this doesn't affect the font size in the textedit window. A 
font size can be selected by clicking on the desired size or by 
typing in the font size. Numbers and the ‘back space’ character 
are assumed to be an input to alter the font size, whilst all other 
characters (except ‘cr’ & ‘enter’) are used to find a matching font 
name. The font style has been separated into two sections, 
‘spacing’ (condense and extend) and ‘style’ (outline, bold, etc). 
When the dialog box is first displayed the radio buttons and check 
boxes reflect the current settings. If their settings are altered it is 
possible to reset them to their original values by clicking on the 
group title concerned (either ‘spacing’ or 'style"). The settings 
are only reset if the mouse is released inside the title. To indicate 
that the mouse is inside the title the thickness of the frame around 
the group doubles. This type of facility (interface) lends itself to 
having the groups set to normal or plain if a double click occurs 
in the title, something which I haven't implemented here. 

At the bottom of the dialog box is displayed some (sample) 
text showing the affect of the selected settings. The sample text 
will only be displayed if the current settings of font name and size 
are valid. A valid font size can be from 4 to 127, normal 
quickdraw limitations. 

If the Ok button is selected or the ‘cr’ or ‘enter’ keys аге 
pressed while the current settings are invalid an alert box is 
displayed indicating which setting isn't valid. 


FontMap 
To produce the dialog box I require the names of the 
available fonts on the system as well as the sizes available for 


each font. The idea of a font menu with a range of font sizes on 
it (ie MacWrite) is relatively easy, all that is required is to test if 
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the selected font has a desired size. If it does then the size is 
shown in outlined style, whilst if it doesn't its style is plain. To 
find every size available on the system for a particular font name 
is a little harder. I decided to produce a relocatable block which 
would contain the names of all the fonts (in alphabetical order) 
and the sizes of each font (in numerical order). Doing this 
reduces the amount of time required to set-up the Font Name and 
Font Size Selection Windows. Note that even some commercial 
software doesn't bother to alphabetize font lists! A graphical 
representation of the FontMap is shown in Fig 3. The first (word) 
field contains the number of different fonts minus one. Then 
there are font references, one reference (of three words) for each 
font. The first field is the font number, the next is the offset to the 
fontname and the last is the offset to the font size list. Both offsets 
are from the start of the FontMap. The font references are sorted 
into the alphabetical order of the fontnames. The space allocated 
for each font name is the smallest number of even bytes that the 
name will fit in. The font sizes for each font are sorted into their 
numerical order within each font size list. The first word of the 
font size list is the number of font sizes in the list, then follows 
the font sizes, one word per font size. The handle to the Map is 
stored for access by the FontDialog routine and could be used to 
prepare the font sizes in a menu. By having the names and sizes 
sorted within FontMap it means that when they are placed into a 
list their cell position relates to their position in the FontMap. 

Apple have laid down in their user interface guidelines that 
font sizes that exist on a system be represented in some way, as 
in outlining in a menu etc. With the new font family resources 
(FOND's & ‘NFNT’s) it is possible to have a font that already 
has a style attribute associated with it, like Geneva Shadow. How 
are these fonts to be represented so that the usercan tell them apart 
from a plain font size? The text sample is one solution and 
perhaps there are others. 


Creating the Font Map 


The SetupFontMap routine is called at the start of a program 
sothatthe FontMapcan be used to set up the font size menu items. 
The routine, first of all evaluates what size to make the Map 
(relocatable block). It examines each *FONT' resource on the 
system and determines if the resource contains a font name or a 
font size. If the resource is a font name, the font (resource) ID and 
the pointer to the name are stored on the stack. If the resource is 
a font size, the font (resource) ID is stored in a non-relocatable 
block (SizeBlock). As each resource is examined, arunning total 
is kept of how large to make the FontMap and how many different 
fonts there are. The FontMap is created and the number of font 
names minus one is loaded into the first field. The font ID’s and 
name pointers are loaded into the font references from the stack. 
The font references are then sorted into the alphabetical order of 
the font names. The font names are then loaded into the Map, 
disposing of their original non-reloctable block in the process 
and replacing the name pointer with an offset. SetupFontMap 
then goes through SizeBlock and loads in all the font sizes 
associated with the first font. The sizes are then sorted into 
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numerical order. SetupFontMap then continues until all fonts 
have their sizes loaded and sorted. All temporary blocks are 
disposed of as the routine is finished with them. The FontMap is 
then unlocked and control returns to the main program. 

This routine should be rewritten so that it examines the font 
resources (“FOND ‘, ‘FONT’ and ‘МЕМТ”) and the font re- 
sources associated with a document. It should also be recalled 
each time a new document is accessed in case there is a new font 
resource associated with it. But that's a task I'll leave for you. 
[Note that Apple discourages the use of fonts within documents 
now. -Ed] 


Font Dialog Mechanics 


The FontDialog routine would generally be accessed by the 
selection of a menu item. The items associated with a dialog are 
stored in an item list which contains the item type, whether it's 
enabled or not and a pointer to the routine that will draw the item, 
as wellasother variables. The order of the items in the list is very 
important (as I found out). The items are drawn and accessed in 
the order that they appear in the item list. If items overlap, the 
item highest in the list (lowest item number) takes precedent. I 
wanted to set up the ‘spacing’ and ‘style’ groups as shown іп Fig 
1 so that if I clicked on either the title or a control, the program 
returned from the ModalDialog trap. At this stage of writing the 
program I wasn't using a UserFilter so I had to create routines to 
draw the bold frame around the Ok button and thin frames around 
the control groups. The problem arose when I wanted to draw the 
frame and the group title so that the frame wasn't drawn through 
the title (as per Fig 1). If the frame is drawn then the title, the 
routine that draws the title erases a section of the frame where the 
title goes. To do this the useritem would have to havea lower item 
number than the title. The useritem that represented the frame 
was disabled so I thought that the other items that were enabled 
wouldn’t be affected by it. Wrong! By placing the useritem 
higher in the item list than the other items I had made all the lower 
items except for the top half of the title effectively invisible/ 
disabled. To get around this problem (before I used a UserFilter) 
I placed the useritem lower in the item list and wrote a subroutine 
similar to TrackHeading. The routine created aregion consisting 
of the useritem rect minus the group title rect, and made it the 
clipping region, it then drew a frame around the useritem rect and 
reset the clipping region. For details on regions and clipping 
check Chris Derossi’s article on “Quickdraw Does Regions!” 
(Pascal Procedures) in MacTutor Vol 1 No 3, February 1985. 
When a User Filter is used, the programmer isn’t confined to 
accessing the dialog items in their order, which simplifies the 
drawing of the items. 

The FontDialog routine creates a non-relocatable block into 
which it stores all its variables. This was done so that memory is 
allocated only when the routine is called. It allows the main 
program to check to see if there is enough spare memory before 
the routine 1$ called, or the routine could become a separate code 
segment that isn’t loaded into memory until it’s needed. The 
routine takes copies of the font number, size and face (style) that 
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are passed to it so that these can be altered without affecting the 
original values, in case the user decides to cancel the dialog. The 
routine only accepts a single font variation (number, size and 
style), it isn’t suitable for altering multiple font variations. 

The spacing radio buttons and style check boxes are set up 
to display the original settings. I made the condense and extend 
style variations radio buttons because there is no point in both 
variations being selected (they cancel one another out). 

The Font Name and Size Selection Windows are then 
created and the available font names and sizes are loaded into 
their respective list. Each list has its selection flags set so that 
only one cell is selected at a time and empty cells aren't se- 
lectable. Even though the selection flag was set so that only one 
cell is selected, I found that I could select more than one cell by 
using the LSetSelect trap. I wanted to set acell and I assumed that 
the List Manager would deselect the currently selected cell. 
Instead I had to deselect the currently selected cell and then select 
the desired cell (as shown in DKeyDown). When the mouse is 
used to select a cell, only one cell is selected, all others are 
deselected. 

Only enough cells are created in each list to contain the font 
names and sizes. In some cases there are blank lines in the list. 
Clicking below the cells deselects the current selection, some- 
times. For some reason it is possible to click below the cells in 
one spot and have the selection deselected while not in others. 
The area in which this occurs is the height of a cell. 

A Sample Display Text Edit Record is then setup so that the 
"STR ' resource number 264 is displayed in the useritem rect at 
the bottom of the dialog box. The string is displayed with the 
current font settings, if they are valid, if they aren't valid then no 
text is displayed. The text is centered horizontally within the 
useritem rect, and also vertically if all the lines are visible. 

The handles of the string resources to be used by the alert 
window are then loaded into the local variable block. 

As the user modifies the settings in the dialog box, the 
routine checks to make sure that they are valid. If they aren't 
valid a flag (OkActive) is cleared. I originally set the Ok button 
to be hilited with #254 (if the selections are invalid) which is 
supposed to make the control inactive but still indicate if it has 
been clicked in. When I did this, I found that the Ok button would 
be grey but it wouldn't indicate if it was clicked in. If I dragged 
the mouse an outline of the Ok button would move in the vertical 
axis. The problem occured when I let the default Modal Dialog 
routine handle the mouse or when I caught the event in the 
UserFilter and used the TrackControl trap. For this reason I’ve 
leftthe Ok button active when the settings are invalid and display 
an alert if the Ok button, ‘cr’ or ‘enter’ are selected. Before the 
alert is displayed the routine determines which variables aren't 
valid and sets up the param strings accordingly. I haven't 
checked to see if this still occurs since my Mac has been 
"enhanced". From a user interface perspective it is good practice 
to inform the user what the problem is instead of not accepting 
their input or sounding a beep. 

After the items have all been set up the ModalDialog trap is 
called. 
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Dialog Filter Proc 


The DUserFilter filters all the events that it needs to handle 
and lets the default routine handle the remainder (by returning 
false). DUserFilter handles its events and returns true and an item 
No. if the main program is to do some variable updating or house 
keeping due to the event (ie a new font name is selected). When 
the DUserFilter handles an event and a setting hasn't altered, ie 
aclick on the selected font name, the event is converted to a null 
event. 

DNull checks to see if the mouse is within the textedit rect, 
if itis it converts the cursor to a handle, otherwise it sets it to the 
arrow. This section of code could be sped up by storing the 
textedit item rect in the local variable block instead of using the 
GetDItem trap every time. When ever a font attribute is altered 
the sample text is erased and the routine waits until KeyThresh 
ticks have occured and then redraws the sample with the new 
attributes. The DNull code checks to see if KeyTresh ticks have 
passed and if the sample requires updating. If it does then the 
DUserFilter returns true and item number 21 (a disabled us- 
eritem). 

DMouseDown handles the mouse down events within the 
two group titles and the two list windows. All other mouse down 
events are handled by the default ModalDialog routines. When 
a mouse down occurs in either of the two group titles the routine 
(TrackHeading) tracks the mouse to see if itis released in itor not. 
If itis, ModalDialog returns with the item number, otherwise the 
event is set to null. When a mouse down occurs in either of the 
List Manager windows the routines check to see if the selection 
has altered. If it has ModalDialog returns with the item number, 
otherwise the event is set to null. 

DKeyDown checks for a ‘cr’ or ‘enter’ key and returns item 
No 1 (Ok button) if it finds one. It then checks to see if a number 
or ‘back space’ character has been pressed, if one has it deselects 
the selected cell in the Font Size Selection Window (if one is 
selected) and returns false for the default ModalDialog routine to 
handle it. DKeyDown then uses the character to search for a font 
name (NameSearch), as described in the User Interface section. 
The List Manager trap LSearch isn't suitable because it only 
checks for exact matches and I required the routine to check 
strings using the [UMagString trap. The FontMap is searched 
through because it is quicker than using the List Manager 
routines to check each cells contents. The routine then makes 
sure the desired cell is selected and visible. 

DUpdate updates all the items in the dialog box. The update 
event removes the need to have an item number for every item 
that is drawn. A prime example is the bold box around the Ok 
button, another is the frame around the textedit item. Items don't 
have to be drawn in the order in which they appear in the dialog's 
item list. This allows the frames to be drawn around the ‘spacing’ 
and ‘style’ control item groups before the group titles are drawn. 
The programmer has complete control over what is drawn in the 
dialog and could in fact draw something that isn’t related to an 
item in the item list. When lists are drawn they don’thave a frame 
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drawn around them, so ’уе had to include one on each list. After 
everything has been updated the event is set to a null event 
(SetoNull) and returned. 

DActivate activates the dialog box (the two list windows and 
the dialog box's text edit record). I've also included the code to 
deactivate the dialog box, even though it never gets used. When 
the ShowWindow trap is called to display the dialog box the 
window is created, a deactivate event is created for the original 
front window as is an activate event for the dialog window. The 
main program's deactivate code isn't accessed because its event 
loop has been broken, the main program has to deactivate the 
front window before the dialog box routine is called. DActivate 
has to be able to filter out the (de)activate event for the original 
front window and not handle it. When the alert is shown, the 
dialog should be deactivated (just like the case above) with 
similar code to that in DDeactivate. The LActivate trap removes 
(hides) scroll bars when the list is deactivated instead of inacti- 
vating them so I didn't include the deactivate code because it was 
visually undesirable (sloppy). 

The routines that handle the result of the ModalDialog trap 
perform the following functions: 

DOX displays an alert if the settings aren't valid and returns 
to the ModalDialog loop (WaitOk). If the settings are valid the 
original values are replaced with the desired values. The routine 
then passes onto DCancel. 

DCancel closes the dialog box and disposes of the unwanted 
records and the local variable block. When there is a lot of 
information to be included (displayed) in a dialog, it is best to 
initially set the dialog to be invisible, setup the items involved 
and then show the dialog. Thiscreates aclean crisp presentation, 
as opposed to items appearing slowly with delays between items. 
The same philosophy applies when the dialog is being closed. It 
is better to hide the dialog first and then to dispose of the items 
rather than to see items within the dialog (window) disappear 
before the window does, very sloppy. 

Style resets the control check boxes to their original settings 
after the user has clicked in the style title. SStyle toggles a check 
box after it has been clicked in. 

Spacing resets the control radio buttons to their original 
settings after the user clicked in the spacing title. SSpacing sets 
the radio button that was clicked in and clears the other radio 
buttons within the group. 

The ModalDialog default routine handles a mouse down 
event in the control items (radio buttons and check boxes) and 
tracks the mouse and returns (with that items number) if the 
mouse is released within the item. The main routine then alters 
the value ofthe control, knowing that it was clicked in, this allows 
groups of radio buttons to be organised together. 

EontName updates the font number variable after a new font 
name was selected. The Font Size Selection Window is then 
updated to show the sizes associated with the new font name. If 
no font name is selected the Font Size Selection Window is 
cleared. 

FontSize updates the font size variable after a new font size 
was selected from the Font Size Selection Window. The textedit 
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item (No 20) is then updated to display the new font size. If no 
font size was selected the textedit item retains its previous value 
(it isn't set to zero). 

GetEditSize updates the font size variable after the user has 
altered the textedit item through a key stroke (0 through to 9 or 
"backspace') The currently selected size in the Font Size 
Selection Window is deselected. The ModalDialog default 
routine returns with the textedit item number when the mouse is 
clicked within its rect even though its value doesn't change. 

FontSample updates the font attributes associated with the 
sample text at the bottom of the dialog box. The text is then 
centered vertically within the user item rect if the height of the 
text lines is less than the height of the rect. The sample is then 
displayed with the new attributes. 

Each of the above routines have code included in them to 
check if their font variable has in fact altered, if it has the sample 
text is then erased and isn't updated until KeyThresh ticks have 
lapsed. 

ГІ leave the remaining description of the routines to the 
comments placed within each listing. Best of luck with writing 
your dialog. 


This sample program was written 
just to prove it could be done! 


Fig. 4 A simple About Box Dialog 


; File Window.Asm 


; The Window Sample Program issued with the MDS. 
; Modified by Ray.A.Cameron to demonstate a Modal Dialog Box. 
; Mon May 4, 1988 21:29:54 


This application displays а window within which you can 
enter and edit text. Progrem control is through four menus: 
the Apple menu, the File menu, the Edit menu, end the Font 
menu.The Apple menu has the standard desk accessories and an 
About feature. The File menu lets you quit the application. 
The Edit menu lets you cut, copy, paste, and clear the text in 
the window or in the desk accessories. Undo is provided for 
desk accesories only. Command key equivalents for undo, cut, 
copy, and paste are provided. The Font menu lets you display а 
Modal Dialog Box to select a Font Name, Size and attributes. 


|----------------------- Includes 


Include  Traps.D Use System and ToolBox traps 


; 
Include ToolEqu.D ; Use ToolBox equates 
Include  QuickEqu.D ; Use QuickDraw equates 
Include  SysEqu.D ; Use System equates 
Include PackMacs.Txt ; Use Package equates 
ананас нда ыны Use of Registers ----------- 


; Operating Sys and Toolbox callis preserve D3-D7, A2-M. 


; Register use: А5-АТ are reserved by the system 
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р 01-03, A@-A1 are unused 
00 is used аз а temp 


ModifyReg 
MenuReg 
MenuItemReg 
AppleHReg 


TextHReg 
WindowPReg 
EditHReg 


Equ 04 ; modifier bits from GetNextEvent 
Equ 05 ; menu ID from MenuSelect , MenuKey 
Equ 06 ; item ID from MenuSe lect, MenuKey 
Equ 07 ; handle to the Apple Menu 

Equ А2 ; handle to TextEdit record 

Equ A3 ; pointer to editing window 

Equ A4 ; handle to Edit menu 

ecce Egua teg s 


; These are equates associated with the resources 
; for the Window example. 


AppleMenu Equ 
About I tem 


FileMenu 
QuitItem 


EditMenu 
UndoItem 
CutI tem 
CopyItem 
PasteI tem 
Clear Item 


FontMenu 
DialogItem 


AboutDialog 
ButtonItem 
ASample 


1 ; First item іп MENU resource 


Equ 1 ; First item in Apple menu 

Equ 2 ; Second item in MENU resource 

Equ 1 ; First item in File menu 

Equ 3 ; Third item іп MENU resource 

Equ 1 ; Items in Edit menu 

Equ 3 ; (Item 2 is а line) 

Equ 4 

Equ 5 

Equ 6 

Equ 4 ; Fourth item in MENU resource 

Equ 1 ; Only item in Font menu 

Equ 1 ; About dialog is DLOG resource #1 
Equ 1 ; First item in DITL used by DLOG #1 
Equ 1 ; Sample Window is WIND resource #1 


; Xdef all labels to be symbolically displayed by debugger. 


Xdef Start 

Xdef Ini tManagers 

Xdef Se tupMenu 

Xdef Se tupW indow 

Xdef SetupTextEdit 

Xdef Activate 

Xdef Deactivate 

Xdef Update 

Xdef KeuDown 

Xdef MouseDown 

Xdef SustemEvent 

Xdef Content 

Xdef Drag 

Xdef InMenu 

Xdef About 

XRef SetupFontMap ; Routines 

XRef FontDialog 

XRef FontMap ; Variable 
С d cde eas Main Program ------------- 
Start 

Bsr Ini tManagers ; Initialize managers 

Bsr Se tupMenu ; Build menus, draw menu bar 

Bsr Se tupW indow ; Draw Editing Window 

Bsr SetupTextEdit ; Initialize TextEdit 

Bsr SetupFontMap ; Initialize the FontMap 
EventLoop ; Main Program Loop 

-SystemTask ; Update Desk Accessories 


; Procedure 


Move.1 


TextHReg, -CSP) 


TEIdle ChTE:TEHandle?); 


; Get handle to text 
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гесога 


-TEIdle ; blink cursor etc. ; Font Menu Set Up 

; FunctionGetNextEventCeventMask: Integer С1г.1 -(SP) ; Space for menu handle 
; Var theEvent: EventRecord) : Boolean Move “ҒопіМепи,-(ӨР) ; Font Menu Resource ID 
Cir -(SP) ; Clear space for result _GetRMenu ; Get File menu handle 
Move “$OFFF,-CSP) ; Allow 12 low events 

Pea EventRecord ; Place to return results Cir -CSP) ; Append to list 
_GetNextEvent ; Look for an event -Inser tMenu ; After Edit menu 

Move (SP )+, D9 ; Get result code 

Веда EventLoop ; No event... Keep waiting -DrewMenuBar ; Display the menu bar 

Bsr HandleEvent ; Go handle event Rts 

Beq EventLoop ; Not Quit, keep going 

Rts ; Quit, exit to Finder оон SetupWindow --------------- 


Note: When ап event handler finishes, it returns the Z flag SetupWindow 
set. If Quit was selected, it returns with the Z flag clear. 
Ап Rts is guaranteed to close all files and launch the Finder. ; FunctionGetNewWindow (windowID: Integer; wStorage: Ptr; 


; behind: WindowPtr) : WindowPtr; 
кже шшк RE CE InitManagers ------------- Cir. -(SP) ; Space for window pointer 
Move ®ASamp le, -CSP) ; Resource ID for window 
InitManagers Pea WindowStorage(A5) ; Storage for window 
Pea -4(А5) ; Quickdraw's global area Move.1 8-1,-CSP) ; Make it the top window 
_InitGraf ; Init Quickdraw -Ge tNewW indow ; Draw the window 
-InitFonts ; Init Font Manager Move.1 (SP), WindowPReg ; Save for later 
Move. 1 8%0000ҒҒҒҒ,00 ; Flush all events 
_F lushEvents -SetPort ; Meke it the current port 
-InitWindows ; Init Window Manager Rts 
-InitMenus ; Init Menu Manager 
Cir.1 -(SP) ; No restart Procedure а саа: кашк арак SetupTextEdit ---------------- 
_InitDialogs ; Init Dialog Manager 
_TEInit ; Init Text Edit SetupTextEdit 
_InitCursor ; Turn on arrow cursor 
Rts ; Procedure ТЕМен CdestRect,viewRect: Rect): TEHandle; 
Cir. -(SP) ; Space for text handle 
cx = SetupMenu --------------- Pea DestRect ; DestRect Rectangle 
Pea ViewRect ; ViewRect Rectangle 
SetupMenu _ТЕ№ ем ; New Text Record 
Move .1 (SP)+,TextHReg ; Save text handle 
; Apple Menu Set Up. Rts 
; FunctionGetMenu (menu ID: Integer): MenuHandle; jose анарын гагын Event Handling Routines -------- 
Cir. - (SP) ; Space for menu handle 
Move ®AppleMenu,-(SP) ; Apple menu resource ID HendleEvent 
-GetRMenu ; Get menu hendle 
Move.1 (SP), AppleHReg  ; Save for later comparison Use the event number as an index into the Event table. 
Моуе.1 СР ),-CSP) ; Copy handle for AddResMenu These 12 events are 811 the things that could spontaneously 
happen while the program is in the main loop. 
Cir -(SP) ; Append to menu 
-InsertMenu ; Which is currently empty Move Modify, ModifgReg ; More useful in а reg 
Move What, Dd ; Get event number 
Move.1 8'DRVR',-CSP)  ; Load all drivers Add 00,00 ; *2 for table index 
-AddResMenu ; And Add to Apple menu Move EventTableCD2),DO ; Point to routine offset 
Jmp EventTableCD0) ; end jump to it 
; File Menu Set Up 
EventTable 
Cir. -CSP) ; Space for menu handle 
Move 8FileMenu,-CSP) ; File Menu Resource 10 Dc.w NextEvent-EventTable  ; Null Event (Not used) 
-GetRMenu ; Get File menu handle Dc.w MouseDown-EventTable ; Mouse Down 
Dc.w NextEvent-EventTable ; Mouse Up (Not used) 
Cir -ОР) ; Append to list Dc.w KeyDown-EventTable ; Key Down 
-InsertMenu ; After Apple menu Dc.w NextEvent-EventTable ; Key Up (Not used) 
Dc.w KeyDown-EventTable ; Auto Key | 
; Edit Menu Set Up Dc.w Update-EventTable ; Update 
Dc.w NextEvent-EventTable ; Disk (Not used) 
С1г.1 -(SP) ; Space for menu handle Dc.w Activate-EventTable ; Activate 
Move SEditMenu,-(SP) ; Edit menu resource ID Dc.w NextEvent-EventTeble ; Abort (Not used) 
-GetRMenu ; Get handle to menu Dc.w NextEvent-EventTable ; Network (Not used) 
Move.1 (SP),EditHReg ; Save for later Dc.w NextEvent-EventTable ; 1/0 Driver (Not used) 
; Leave on stack for Insert 
то a a Event Actions ----------------- 
Cir -С($Р) ; Append to list Activate 


-Inser tMenu ; After File menu 
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Ап activate event is posted by the system when а window 
needs to be activated or deactivated. Тһе information that 
indicates which window needs to be updated was returned by the 
NextEvent call. 


Стр.1 Message,WindowPReg ; Маз it our window? 


Bne NextEvent ; No, get next event 
Btst  "activeFlag,ModifyReg ; Activate? 
Вед Deactivate ; No, go do Deactivate 


To activate our window, activate TextEdit, and disable Undo 
since we don't support it. Then set our window as the port 
since an accessory mau have changed it. This activate event 
was generated by SelectWindow as a result of а click in the 
content region of our window. If the window had scroll bars, 
we would do ShowControl and HideControl here too. 


; Procedure TEActivate (hTE: TEHandle); 
Моуе.1 TextHReg, - (SP) ; Move Text Handle To Stack 
_TEActivate ; Activate Text 


; Procedure DisableItem (menu:MenuHandle; item: Integer); 


Move. 1 EditHReg, -CSP) ; Get handle to the menu 
Move ®Undol tem, -CSP) ; Enable ist item Cundo) 
DisableItem 
SetOurPort ; used by InAppleMenu 
Моуе. 1 WindowPReg, -CSP) ; Әп accessory might have 
-SetPort ; changed it. 
NextEvent 
Moveq 80,00 ; Say that it's not Quit 
Rts ; return to EventLoop 
Deactivate 
Моуе. ] TextHReg, -CSP) ; Get Text Handle 
_TeDeActivate ; Un Activate Text 
Move. ] Edi tHReg, -CSP) ; Get handle to the menu 
Move ®Undol tem, - CSP) ; Enable Ist item Cundo) 
-EnableItem 
Вга NextEvent ; бо get next event 
Update 


The window needs to be redrawn. Erase the window and then 


call TextEdit to redraw it. 


; Procedure BeginUpdate (theWindow: WindowPtr); 
Move.1 WindowPReg,-CSP) ; Get pointer to window 
-BeginUpDate ; Begin the update 


; EreseRect (rUpdate: Rect); 
Pea ViewRect 
-EreseRect 


; Erese visible area 


; TEUpdate CrUpdate: Rect; hTE: TEHandle); 

Pea ViewRect ; Get visible area 
Move.1 TextHReg, -CSP) ; апа handle to text 
-TEUpdate ; then update the window 


; Procedure  EndUpdate CtheWindow: WindowPtr); 


Моуе. ] WindowPReg,-(SP) ; Get pointer to window 

-EndUpdate ; end end the update 

Bra NextEvent ; Go get next event 
KeyDown 


First check to see if it was a command 
Otherwise pass the key to TextEdit. 


A key was pressed. 
key. If so, go do it. 


Btst 8OmdKey,ModifyReg ; Is command key down? 
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Bne CommandDown ; handle command key 

; Procedure ТЕКеу (кеу: CHAR; hTE: TEHandle); 

Move Message*2, -(SP) ; Get character 

Move.1 TextHReg, -CSP) ; end text record 
_ТЕКеу ; Give char to TextEdit 
Bra NextEvent ; бо get next event 


CommandDown 


The command key was down. Call MenuKey to find out if it 
was the command key equivalent for a menu command, pass the 
menu and item numbers to Choices. 


; FunctionMenuKey (ch:CHAR): LongInt; 


Clr. -(SP) ; Space for Menu and Item 

Move Message*2, -(SP) ; Get character 

-MenuKey ; Зее if it's а command 

Move (SP )+, MenuReg ; Save Menu 

Move (SP)+,MenuItemReg ; and Menu Item 

Bra Choices ; Go dispatch command 
нысы Mouse Down Events And Their Actions----- 
MouseDown 


If the mouse button was pressed, we must determine where 
the click occurred before we can do anything. Call FindWindow 
to determine where the click was; dispatch the event according 
to the result. 


; FunctionF indWindow CthePt: Point; 

Ver whichWindow: WindowPtr): Integer; 
; Space for result 

Point, -CSP) ; Get mouse coordinates 


Clr —-(SP) 
Move.1 


Pea WWindow ; Event Window 

FindWindow ; Who's got the click? 

Move (SP)+,D0 ; Get region number 

Add 00,00 ; *2 for index into table 

Move WindowTebleCD0),DO ; Point to routine offset 

Jmp WindowTableCDO) ; Jump to routine 
WindowTable 

Dc.w NextEvent-WindowTable ; In Desk (Not used) 

Dc.w InMenu-WindowTable ; In Menu Bar 

Dc.w SystemEvent-WindowTable ; System Window 

Dc.w Content-WindowTable ; In Content 

Dc.w Drag-WindowTable ; In Drag 

Dc.w NextEvent-WindowTable ; In Grow (Not used) 

Dc.w NextEvent-Windowlable ; In Go Away (Not used) 
SystemEvent 


The mouse button was pressed in а system window. Sys- 
temClick calls the appropriate desk accessory to handle the 
event. 


SystemClick CtheEvent: EventRecord; 
; theWindow: WindowPtr); 

Pea EventRecord ; Get event record 
Моуе. ] WWindow,-CSP) ; and window pointer 
-SystemCl ick ; Let the system do it 
Bre NextEvent ; бо get next event 


; Procedure 


Content 


The click wes in the content area of а window. If our 
window was in front, then call Quickdraw to get local coordi- 
nates, then pass the coordinates to TextEdit. We also deter- 
mine whether the shift key was pressed so TextEdit can do 
shift-clicking. If our window wasn't in front, Move it to the 
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front, but don't process click. 


С1г.1 -(SP) ; clear room for result 
-FrontWindow ; get FrontWindow 

Move.1 (SP )+, D8 ; Is front window pointer 
Cnp.1 WindowPReg,D@ ; same as our pointer? 
Beq.s el ; Yes, call TextEdit 


We weren't active, select our window. This causes an 
activate event. 


; Procedure SelectWindow (theWindow: WindowPtr); 

Move. ] WWindow,-CSP) ; Window Pointer To Stack 
-SelectWindow ; Select Window 

Bra NextEvent ; end get next event 


e1 
; We were active, pass the click (with shift) to TextEdit. 


; Procedure GlobalToLocal (Ver pt:Point); 
Pea Point ; Mouse Point 
-ClobalToLocal ; Global To Local 


; Procedure TEClick (pt: Point; extend: Boolean; hTE: 
TEHandle); 

Move.1 Point,-CSP) ; Mouse Point (GTL) 

Btst *shiftKey, ModifyReg ; Is shift key down? 

Sne 00 ; Тгие if shift down 


Note: We want the Boolean in the high byte, so use Move.b. 


The 68000 pushes әп extra, unused byte on the stack for us. 


Move.b D,-CSP) 
Move.1 TextHReg,-CSP) ; Identify Text 
-TEClick ; TEClick 
Вга NextEvent ; бо get next event 
Drag 
Move.1 WWindow,-CSP) ; Pass window pointer 
Move.1 Point,-CSP) ; mouse coordinates 
Pea WBounds ; апа boundaries 
"гади indow ; Drag Window 
Bra NextEvent ; Go get next event 
InMenu 
Cir.) -(SP) ; Get Space For Menu Choice 
Move.1 Point, -CSP) ; Mouse At Time Of Event 
—MenuSe lect ; Menu Select 
Move CSP )+, MenuReg ; Save Menu 
Move (SP)*,MenuItemReg ; and Menu Item 


On entry to Choices, the resource ID of the Menu is saved 
іп the low word of а register, and the resource ID of the 
MenuItem in another. The routine MenuKey, used when а command 
key is pressed, returns the semeinfo. 

Choices ; Called by command key too 
Стр AppleMenu,MenuReg ; Is It In Apple Menu? 

Beq InAppleMenu ; 6o do Apple Menu 

Стр *FileMenu,MenuReg  ; Is It In File Menu? 

Вед InF i leMenu ; бо do File Menu 

Стр "EditMenu,MenuReg  ; Is It In Edit Menu? 

Beq InEditMenu ; бо do Edit Menu 

Сар FontMenu,MenuReg ; Is It In Font Menu? 


Beq InFontMenu ; бо do Font Menu 
ChoiceReturn 
Bsr UnHiliteMenu ; Unhighlight the menu 
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bar 

Bra NextEvent ; Go get next event 
InF i leMenu 

Cmp "QuitItem,MenuItemReg ; Is It Quit? 


Bne  ChoiceReturn ; No, Go get next event 


Bsr UnHiliteMenu ; Unhighlight the menu bar 
Move 8-1,00 ; Say it жаз Quit 
Rts 

InEditMenu 


; First, call SystemEdit. If a desk accessory is active that 
uses the Edit menu (such as the Notepad) this lets it use our 
menu. Decide whether it was cut, copy, paste, or clear. 
Ignore Undo since we didn't implement it. 


Bsr SystemEdit ; Desk accessory active? 


Bne ChoiceReturn ; Yes, SystemEdit handled it 
Стр — f*CutItem,MenuItemReg; Is It Cut? 
Beq Cut ; Yes, go handle it 
Стр "CopygItem,MenuItemReg ; Is it Copy? 
Beq Copy ; Yes, go hendle it 
Cmp 8SPaesteItem,MenuItemReg ; Is it Paste? 
Beq Paste ; Yes, go handle it 
Cmp 8ClearItem,MenuItemReg ; Is it Clear? 
Beq Clearit ; Yes, go handle it 
Вга ChoiceReturn ; Go get next event 
InFontMenu 
Cmp #DialogItem,MenuItemReg; Is It Dialog? 


Bne ChoiceReturn ; No, Go get next event 


; Procedure TEDeActivate (hTE: TEHandle) 
Move. 1 TextHReg, -CSP) ; Identify Text 
-TEDeAct ivate ; Deactivate Text 


; Obtain the current Font number, size and attributes to setup 
the dialog box. 


Movea.]  TextHReg, Ad ; Handle to the TE record 
Movea.1 — (Аб), Аб ; Pointer to the TE record 
Move.w teFont(A0),D0 ;- Font Number 
Cmp.w 81,00 ; Default number? 
Bne.s 00 ; No, > 00 
Move.w ApFontID,D0 ; Yes, load default number 
80 Move.w D0,DtxFont(A5) 
Clr.w 00 ;- Font Face 
Move.b teFaceCA2),D0 ; Place the attribute bits in 
the 
Move.w DO,DtxFaceCA5) ; low byte of DtxFaceCA5). 
Move.w teSize(A0),D0 ;- Font Size 
Bne.s 81 ; Default size, № -> 61 
Move.b FMDefeultSize,DO ; Yes, load default size 
61 Move.w DO ,DtxSizeCAb) 
Clr.w -CSP) 
Pea DtxFontCA5) ; Load the font's number address 
Pea DtxFaceCA5) ; Load the font's face address 
Pea DtxSizeCA5) ; Load the font's size address 
Jsr FontDialog 


Test to see if the okButton was pressed Cie install the new 
Font variables). If the cancelButton was pressed leave the 
Font variables as theu ere. 

Move.b (5Р2%,00 

Beq.s 62 


Update the Font number, size, and face fields in the 
textedit record. The teAscent and teLineHite fields also 
require up dating. Reset the port to the textedit window, 
Since the current GraphPort has been changed by the FontDia- 
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log routine. 


Move.1 WindowPReg, -CSP) 
-SetPort 

Move.w DtxFontCA5), -CSP) 
-TextFont 

Move.w DtxFaceCA5)2, -CSP) 
_Тех{Гасе 

Move.w DtxSizeCA52, -CSP) 
-TextSize 


; Procedure GetFontInfo (Var Info: FontInfo) 
Pea Inf oCA5) 


-GetFontInfo 
Movea.]  TextHReg,A1 ; DeReference the Handle 
Movea.]  (A12,A1 
Move.w DtxFontCA5), teFont (A1) ; teFont 
Move.b DtxFace+1CA5),teFaceCAl) ; teFace 
Move.w DtxSizeCA5), teSizeCA1) ; teSize 
Move.w Infotascent(A5), teAscent(Al) ; teAscent 
Move .w Infotascent(A5), 00 ; teLineHite 
Add.w Info*descent(A5),D0 
Add .w Infot+leading(A5), DØ 
Move.w DØ, teLineHiteCA1) 

62 Bre — GoSetOurPort 

InAppleMenu 


(тр X "AboutItem,MenuItemReg 
Beq About 


; Is It About? 
; If So Goto About.. 


; Procedure GetItem (menu: MenuHandle; item: Integer; 
Ver itemString: Str255); 


love .1 AppleHReg, -CSP) ; Look in Apple Menu 
Move MenuItemReg,-C(SP) ; What Item Number? 
Pea DeskName ; Get Item Name 
-GetTtem ; Get Item 


; FunctionOpenDeskAcc CtheAcc: Str255) : Integer; 


Cir -CSP) ; Spece For Opening Result 
Pea DeskName ; Open Desk Acc 
-OpenDeskAcc ; Open It 
Move (SP)*,D0 ; Pop result 
GoSetOurPort 
Bsr SetOurPort ; Set port to us 
Вга ChoiceReturn ; Unhilite menu and 
return 
СЕЗЕ ЕС Text Editing Routines --------- 
Cut ; CUT 
Move.1 TextHReg, -CSP) ; Identify Text 


-TECut ; Cut it and copy it 
Bra ChoiceReturn ; Go get next event 
Copy ; C0 
Move.1 TextHReg, -CSP) ; Identify Text 
_ТЕСору ; Copy text to clipboard 
Bre — ChoiceReturn ; 60 get next event 
Peste j 
Move.1 TextHReg, -CSP) ; Identify Text 
—TEPeste ; Peste 
Bra X ChoiceReturn ; 60 get next event 
ClearIt ¿CLEAR 
Move.1 TextHReg, -CSP) ; Point to text 
-TEDelete ; Clear without copying 


Вга — ChoiceReturn ; Go get next event 


SystemEdit does undo, cut, copy, paste, and clear for desk 


accessories. It returns False (Вед) if the active window 
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doesn't belong to а desk accessory. 


SystemEdit 


; FunctionSystemEdit CeditCmd: Integer): Boolean; 

Cir -ОР) ; Space for result 

Move MenultemReg,-(SP) ; Get item in Edit menu 
Subq 81, ($Р) ; SystemEdit is off by 1 


-SysEdit ; Do It 
Move.b (ӨР2%,00 ; Pop result 
Rts ; Beq if NOT handled 
Unhili teMenu 
; Procedure HiLiteMenu (menuID: Integer); 
Cir -(SP) ; M1 Menus 
-HiL iteMenu ; UnHilite Them A11 
Rts 
camur n CL ERES Misc Routines------------ 
About 


; FunctionGetNewDialog CdialogID: Integer; dStorage: Ptr; 
behind: WindowPtr) : Dia- 


logPtr 
С1г.1 -(SP) ; Space For dialog pointer 
Move BAboutDialog,-(SP) ; Identify dialog rsrc # 
Pea DStorage ; Storege area 
Move.1 8-1,-CSP) ; Dialog goes on top 
-GetNewDialog ; Display dialog box 
Move.1 (SP),-CSP) ; Copy handle for Close 

; Handle on stack 

-SetPort ; Meke dialog box the port 
Move.1 TextHReg,-(SP) ; Identify Text 
-TEDeAct ivate ; Deactivate Text 

Wai tok 


; Procedure ModalDialog (filterProc: ProcPtr; 
Ver itemHit: Integer); 


Gra -(SP) ; Cleer space For handle 
Pea ItemHit ; Storage for item hit 
-ModalDialog ; Wait for а response 
Move ItemHit,D0 ; Look to see what was hit 
Стр 8ButtonItem,DO ; was it OK? 
Bne WaitOK ; No, wait for OK 
-CloseDialog ; Handle already on stack 
Bra GoSetOurPort ; Set port to us end return 
3; edema mon Data Starts Here ------------ 
EventRecord ; NextEvent's Record 
What: Dc 0 ; Event number 
Message: Dc.1 0 ; Additional informa- 
tion 
When: Dc.1 0 ; Time event was 
posted 
Point: Dc.1 0 ; Mouse coordinates 
Modify: Dc 0 ; State of keys and 
button 
WWindow: Dc.1 0 ; Find Window's Result 
DStorage Dcb.w DWindLen,Q ; Storage For Dialog 
DeskName Dcb.w 16,0 ; Desk Accessory's 
Name 
WBounds Dc 28,4,308,508 ; Dreg Window's Bounds 
ViewRect Dc 5,4,245,405 ; Text Record's View 
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Кесі 


DestRect Dc 5,4,245,405 ; Text Record's Dest 
Rect 

ItemHit Dc 0 ; Item clicked in 
dialog 

ose SECOURS Nonrelocatable Storage --------- 


Variables declared using Ds are placed іп а global space 
relative to А5. When these variables are referenced, А5 must 
be explicitly mentioned. 


DtxFont Ds.w 1 

DtxFace Ds.w 1 

DtxSize Ds.w 1 

Info Ds.w 4 ; FontInfo Record 
WindowStorage X Ds.w WindowSize ; Storage for Window 
End 

ОЕ FontDia log = 


; Written by Ray.A.Cameron 
; Version 1 
‚Мед May 6, 1988 21:00:51 


ItemHit Equ$D4 

loc_pt Equ$D6 

InitBounds Equ$DA 

TextCursor Еди$Е2 

thename Equ$E6 

pnState Equ$ 1E6 
Stringi Equ$1F8 
Str ing2 Equ$ 1ЕС 
String3 Equ$200 
Sample Equ$204 
SampleRect Еаи$208 
SampleTicks  Equ$210 
updated 

info Equ$2 14 
search Equ$21C 
GlobalslengthEqu$23C 


we `. We We `. `. We We We We We 


Item clicked in dialog 
mouse location 
Init size of Lists 
Handle to the [Beam cursor 
Text string 
Original state of the pen 
Alert text string! 
Alert text string2 
Alert text strings 
Sample Text Edit Handle 
Sample Text Edit Rect 

; Ticks when Sample required 


; GetFontInfo record 
; String to search Font Name List 


; This routine receives the following inputs: 
teFont: The current font's number 
teFace: The current type face's attributes in low byte 


Bit 3 - Outline 
Bit 4 - Shadow 
Bit 5 - Condense 


Bit 6 - Extend 


М 

; Bit Ø - Bold 

; Bit 1- Italic 

; Bit 2 - Underline 

; teSize: The current font's size 


À ModalDialog box 


is displayed to allow the user to choose 
the font attributes that they desire. 


If the Ok button, enter 


key or carriage return is pressed the selected values will 
replace the original values otherwise the values remain the 


same. 


XDef FontDialog ; Routine's name 
XRef FontMap ; Veriable's name 
jue на Includes ------------- 
Include Traps.D ; Use System and ToolBox traps 
Include ToolEqu.D ; Use ToolBox Equates 
Include QuickEqu.D ; Use QuickDraw Equates 
Include SysEqu.D ; Use System Equates 
Include PackMacs . Txt ; Use Package Equates 
Include FontMacros.Txt ; Use Macro file 
P SaaSonaa== Equates ---------- 
FontOPtr EquA4 
FDialog Equ260 ; Font dialog is DLOG resource 8260 
ADialog Equ268 ; Alert dialog is МЕТ resource #269 
True Equ 1 ; Boolean True 
False Equé ; Boolean False 
enterCode Equ3 ; ASCII Enter 
bsCode Еам8 ; ASCII Back Space 
er Code Equ 13 ; ASCII Carriage Return 
рагатй Equa ; Offset to string В in DAStrings 
рагамі Equ4 ; Offset to string 1 in DAStrings 
param2 Equ8 ; Offset to string 2 in DAStrings 
OkActive Еам0 ; OkActive bit within Dialog Flags 
SUpdate Equ 1 ; Sample update bit within Dialog Flags 
SRect Equ2 ; Sample rect bit within Dialog Flags 
SKey Equ3 ; Sample key bit within Dialog Flags 
Mou Font Dialog Deta Record ------- 
DStorage Equ$? ; Storage for the Dialog Record 
TempFont Equ$AA ; Currently selected font number 
TempFace Equ$AC  ; Currently selected font style 
TempSize Equ$AE ; Currently selected font size 
DF lags Equ$80 ; Dialog Flags 
NameListH Equ$B2 ; Font Name Selection List's Handle 
NameCe11 Equ$B6 . Font Name selected cell 
SizeListH Equ$BA ; Font Size Selection List's Handle 
SizeCell Equ$BE ; Font Size selected cell 
TempCe11 Equ$C2 ; Temporary Cell variable 

Item Equ$C6 ; Item's handle or procedure 
Itemtype Equ$CA ; Item's type 

I temBox Equ$CC ; Item's enclosing rect 
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FontDialog 


Link А6,80 

‚ Boolean result 
DtxFont Address 
DtxFace Address 


20(A6) ; Ok or Cancel 
16(А6) ; Address of current Font number 
12€A6) ; Address of current Font style 


we `. We `. We DW 


DtxSize Address 8CA6) ; Address of current Font size 
Return Address 4CA6) 
Old Аб (Аб) 

Моуеп.1 00-ОТ7/А0-А4,-(ӨР) ; Save register values. 


Move.w *False,20CA6) ; Set up to return False. 


; Create a non-relocatable block for Font Data Record. 


Move.1 ttGlobalslength,D 

-NewPtr , CLEAR 

Move.1 А0 ,FontDRecCA5) ; Store the pointer. 
Movea. | A0, FontDPtr 

GetPenState  pnState(A4) ; Save the current pen settings. 


; Load the present values of the font number, face апа size 
; into temporary locations. 


Movea.1 16(Ү(62,А0 ; Font number. 
Move.w (АВ), TempFontCA4) 

Movea.1 12(Ү6),А0 ; Font face. 
Move.w (AQ), TempFaceCA4) 

Моуеа. 1 ВСАб),Аб ; Font size. 
Move.w (АВ), TempSizeCA4) 


; Obtain the iBeamCursor's resource and lock it down. 
; Function GetCursor CcursorID: Integer): CursHandle 


Subq.1 84 SP 

Move.w * iBeemCursor , - (SP) 

_бе{Сигзог 

Move.1 (SP)*,TextCursor(A4) 

HLock TextCursor (A4) 

Subq.1 84 SP ; Space Гог dialog pointer. 


Move.w*FDialog,-(SP) ; Identify dialog rsrc 8. 
Move.1 FontÜOPtr,-C(SP) ; Storage area. 
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Моуе. ] 8-1,-CSP) ; Dialog goes on top. 
-GetNewDialog 
-SetPort 


Move.1 OneOne, InitBounds*bottomCA4) 
Bset.b tOkActive,DFlags(A4) ; selections ere valid. 


; Lock FontMap while its information is being accessed. 
HLock FontMap(CA5) 
DeRefHndleFontMapCA52), АЗ 


Set up the Style check boxes so that they show the current 
font's values. 


Move .w TempFace(A4),D0 current face (style) byte. 


Move. #4, -(SP) ` tem No 4. 
Move.w 85, -CSP) ; 5 Items (check boxes). 
Move.w DO,-CSP) ; Bits to set. 


Bsr SControl 


Set up the Spacing radio buttons so that they show the 
current fonts values. 


Move .w TempFace(A4), 00 
Andi .w 1201100000 ,06 


current face (style) byte. 
Examine Condense & Extend. 


w. w. We We 


Bne.s 682 If neither аге set, then 

Move.w 15000 10000,00 add bit to represent "Normal". 
60 Lsr.W 84 DO 

Move.w 811,-CSP) ; Item No 11. 

Move .w 83,-(SP) ; 3 Items (radio buttons). 

Move .w 00,-(5Р) ; Bits to set. 

Bsr SControl 


; Set up the Font Name Selection Window 


GetDItem FontDPtr, #17, ItemtypeCA4), ItemCA4), ItemBoxCA4) 


Subq. 1 #4 SP ; Space for the handle. 

Pea ItemBoxCA4) 

Pea InitBounds(A4) ; Create one cell. 

С1г.1 -(SP) ; Cell size for text. 

Move.w #9 ,-CSP) ; Text definition procedure. 


Move.1 FontDPtr,-CSP) 


Move.b #False,-(SP) ; drewIt 

Move .b #False,-(SP) ; hasGrow 
Move.b "False, -(SP) ; ScrollHoriz 
Move .b True, -CSP) ; scroliVert 
-LNew 


Move.1 (SP),NameListHCA4) ; Store the List's handle. 

DeRefHndle (SP )+, Ad ; Set the selection flags. 

Move .b 8$ 100000 10,5е1Ғ1а05(А0) ; lOnlyOne, lNoNilHil- 
ite 

Move. | 8%-ҒҒҒ 000, МәпеСе11(А4) ; (0,-1), no cell 


Jsr LdNames ; Load the Font Names. 

; Set up the Font Size Selection Window 
GetDItem FontDPtr, #19, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
; Function LNew (rView, dataBounds: Rect; cSize: Point; 


; theProc: Integer; theWindow: WindowPtr; drawIt, hasGrow, 
; scrollHoriz, scrollVert: Boolean): ListHandle 


Subq.1 #4, SP ; Space for the handle. 

Pea ItemBoxCA4) 

Pea InitBoundsCA4) ; Create one cell. 

Clr.1 -($Р) ; Cell size for text. 

Move .w #9, -(SP) ; Text definition procedure. 
Move. 1 FontDPtr,-CSP) 

Move.b tFalse,-(SP) ; drawIt 
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Move.b *False,-CSP) ; hasGrow 
Move.b "False,-CSP) ; ScrollHoriz 
Move.b "True, -CSP) ; ScrollVert 
-L New 


Моуе. ] (SPO,SizeListHCA4) ; Store the List's handle. 
DeRefHndle(CSP)*,A0 ; Set the selection flags. 
Move.b #5 100000 10, зе1Е1а9$(Аб) ; 10nlyOne, lNoNilHil- 
Move.1 "$FFFF0000,SizeCe11CA4) 


Jsr LdSizes ; Load the current Font's Sizes. 


; Set up the Font Size Text Edit item 


Jsr SetEditSize 


; Set up the Sample Display Text Edit Record 


GetDItem FontDPtr, #21, ItemtypeCA4), I temCA4), Samp leRectCA4) 
; Function TENew CdestRect, viewRect: Rect): TEHandle 
Subq. 1 84 SP 

Pea SampleRect(A4) ; Create a new text edit record. 
Pea — SampleRect(A4) 

—TENew 

Move. | (SP +, Samp 1eCA4) ; Store theTEdit handle. 
HLock SampleCA4) 

DeRefHndleSampleCA4), Ad ; Setup the variables. 
Move .w *teJustCenter, teJustCA2) 

Move .b MinusOne, teCROnlyCA2) 


GetResource ‘STR ',#264 ; Obtain the sample text. 
HLock (SP) ; Leave the handle on the stack. 


DeRefHndleCSP),A0 ; Address of text in AQ. 

С1г.1 00 ; Length of text in 00. 

Move.b СА02%,00 

Моуе.1 A8,-CSP) ; Insert the sample string into 
Move.1 00,-(5Р) ; the record. 

Move. | Samp leCA4),-CSP) 

-TEInsert 

HUn lock CSP )+ ; Unlock the string resource. 
Jsr SampleWindow ; Update the TEdit variables. 
HUn lock Samp leCA4 ) 


; Set up the Alert Dialog Variables 


Move .w 8-1 ACount ; Reset the Alert stage to 1. 
GetResource ‘STR ',#261 ; Obtain copies of the Alert 


strings 


Моуе.1 (SP)+,StringiC(A4) ; handles and store for easy 
GetResource ‘STR ',#262 ; access. 

Move.1 (SP)*,String2(A4) 

GetResource ‘SIR ', #263 

Move. | CSP )+,String3CA4) 


; Display the Dialog Window 


ShowWindowFontDPtr ; This posts an Activate event. 


Wai tok 


Pea DUserFilter 
Pea ItemHitCA4) 
-ModalDialog 


Move.w ItemHit(A4),D8 ; Get the itemNo that was Hit. 
Subq.w 81,00 ‚ Allow for по item zero. 


Ls].» — 81/00 : X2 for table index. 

Move.w ItenTableCD22,D8 ; Point to routine offset 

Jmp ItemTableCDO)  ; and jump to it. 
ItemTable 

Dc.w DOk-ItemTable ; Ok Button 
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DOk 


Dc DCancel-ItemTable Cancel Button 

Dc WaitOk-ItemTable Character.. Text (Disabled) 
Dc SStyle-ItemTable Bold Check Box 

Dc SStyle-ItemTable Italic Check Box 

Dc SStyle-ItemTable Underline Check Box 

Dc SStyle-ItemTable Outline Check Box 

Dc SStyle-ItemTable Shadow Check Box 

Dc Style-ItemTable Style Text (Enabled) 
Dc WaitOk-ItemTable ThinBox User Item 


Dc SSpacing-ItemTable Normal Redio Button 

SSpacing-ItemTable Condense Radio Button 
Dc SSpacing-ItemTable ; Extend Radio Button 
Dc Spacing-ItemTable Spacing Text (Enabled) 
Dc WaitOk-ItemTable ThinBox User Item 


WaitOk-ItemTable 
FontName-ItemTable 
WaitOk-ItemTable 


Font N... Text (Disabled) 
NameSel Wind User Item 
Font S... Text (Disabled) 
FontSize-ItemTable SizeSel Wind User Item 
GetEditSize-ItemTable ; Type size Text Edit 
FontSample-ItemTable; Sample Font User Item 


we We We We Me We We We We We We We We We We We We We 


e 
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; If the current Dialog selection isn't valid, set up the 


appropriate param text strings and invoke the Caution Alert. 


Btst.b 8OkActive,DFlags(A4)5; Is the selection valid? 
Bne e3 ; Yes -> 63 
Clr.w 00 ; Set up the three param 
Моуеа. | —*DAStrings, Ad ; text strings. 
Clr.1 param0(A0) 
С1г.1 рагам 1СА@) 
С1г.1 param2CAQ) 
Cmpi.w 9-1, TempFontCA4) ; Is TempFont a valid selection? 
Bne.s 60 ; Yes -> 00 
Bset.b 80,00 ; № -> include related text. 
Move.1 String 1(А42,рагат (Аб) 
80 Cmpi.w %0 Тепрбіге(А4) ; Is TempSize a valid selection? 
Bne.s 61 ; Yes -> 81 
Bset.b 81,06 ; № -> include related text. 
Move.1 Str ing2C(A4)2, param2CA2) 
61 Cmpi.w 83,00 ; If both TempFont and TempSize 
Bne.s 62 ; ere invalid include the conjunctive 
Move. 1 бігіпа3(А42,рагап (А0) ; string (String3). 
62 ; Function CeutionAlert CalertID: Integer; filterProc: 
ProcPtr): Integer 
Subq.1 82 SP 
Move .w ®ADialog, -CSP) 
Cir. -CSP) 
-CeutionAlert 
Addq.1 82 5Р 
Вга WaitOk ; User to alter their selection. 
e3 ; 


д 


If the current Dialog selection is valid, replace the 


original font number, style and size values with the values 
chosen by the user. 


Movea.1 16САб),Аб ; Font number. 
Move .w TempFont(A4 ), (А0) 
Моуев.1 12САб), Аб ; Font style. 
Move .w ТепрҒасе(А4),(А0) 
Movea.]  8(А6), Аб ; Font size. 
Move.w TempSizeCA4), CAB) 
Move.b "True, 20(A6) ; Return True. 
DCancel 
HideWindowFontDPtr 
LMDispose NemeListHCA4) — ; Font Name List. 
LMDispose SizeListH(A4) : Font Size List. 
TEDispose Samp leCA4) ; Sample Text Edit Record. 
CloseDialog FontDRecCA5) 
HUnLock FontMapCA5) ; FontMap . 
HUnLock TextCursor(A4) ; iBeamCursor resource. 
SetPenState pnStateCA4) ; Restore the pen settings. 
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DisposePtr FontDPtr ; Font Dialog Data Record. 
Movem.] (SP)+,D@-D7/A@-A4 ; Restore registers. 
Unik A6 
Моуеа.1 (SP)+,Ad ; Pop args & return. 
Add.1 #12,SP 
Jmp (A0) 

Style 
Move.w ТепрҒасе(А42,02 ; Store for comparison later. 
Movea. | 12(А62,А0 ; Obtain original style values 
Move.w CAG), DØ ; and retain lower five bits. 
Andi .w 8%00011111,00 
Andi .w 8211120909, ТепрҒасе(А4); Clear the lower 5 bits. 
Or.w DØ, ТепрҒасе(А4) ; Combine the two together. 
Вга.5 SetStyle 

SStyle 
Move.w ТепрҒасе(А42,02 ; Store for comparison later. 
Move.w ItemHit(A4),D8 ; Get the itemNo that was hit. 
Subq.w 84 0 
Bchg.b DØ, ТепрҒасе% (А4)  ; Toggle the selected item. 

SetStyle 
Cmp.w TempFaceCA4),D2 ; Has the face altered? 
Beq.s e1 ; No -> 61 
Move.w TempFaceCA4),D0 
; Routine SControl (StItem, NofItems, ValueBits : Integer) 
Move.w 84,-(SP) ; Item No 4. 
Move .w 85, -(SP) ; 9 Items (check boxes). 
Move.w DØ, -CSP) ; Bits to set. 
Bsr — SControl 
Btst.b tOkActive,DFlags(A4)5; Are Dialog selections valid. 
Beq.s e1 ; No, don’ t update the sample. 
Bclr.b 8SRect,DFlags(A4)  ; Erase Sample if it hasn't 
Beq.s 80 been already. 
EraseRect SampleRect(A4) 

60 Bset.b "SUpdate,DFlagsCA4) ; Window requires updating. 
Move. 1 Ticks, Samp leTicks(A4) 

61 Jmp WaitOk 

Spacing 
Move.w ТетрҒасе(А42,02 ; Store for comparison later. 
Movea. 1 12€A6), AØ ; Obtain the original style values. 
Move .w CAO), D8 
Bra.s Se tSpacing 

SSpacing 
Move.w TempFace(A42),D2 ; Store for comparison later. 
Move.w ItemHitCA4),D1 ; Get the item No that was hit. 
Sub.w 811,01 ; Produce іп 08 а byte that 
Move.w 5000 10000,00 ; represents which bit to set. 
Lsl.b 01,00 

SetSpacing 
Andi .w 8411100000,00 ; Clear the lower 5 bits. 
Andi .w 8200011111,TempFace(A4); Clear the top 3 bits. 
Or .w DØ, ТепрҒасе(А4) ; Combine the two together. 
Cmp.w TempFaceCA42,D2 ; Has the face altered? 
Beq.s e2 ; No -> 62 
Move.w ТетрҒасе(А42,00 ; Produce in the first З bits 
Andi .w 8%401100000,00 .оҒ DØ the settings of the 
Bne.s eo ; 3 radio buttons. 
Move.w 8200010000 , 00 

ё? Lsr. b 84 00 

; Routine SContro! (StItem, NofItems, ValueBits : Integer) 

Move. М #11,-CSP) ; Item No 11. 
Move .w #3, (SP) ; 3 Items (radio buttons). 
Move.w DO, -CSP) ; Bits to set. 
Bsr 5Сопіго1 
Btst.b 80kActive,DFlags(A4); Are Dialog selections valid. 
Beq.s 62 ; No, don't update the sample. 
Bclr.b 8SRect,DFlags(A4); Erase Rect if it hasn't 
Beq.s 61 ; been already. 
EraseRect SampleRect(A4) 

61 Bset.b 8SUpdate,DFlagsCA4) ; Window requires updating. 
Моуе.1 Ticks, SanpleTicksCA4) 
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82 Әтр WaitOk 
SContro] 
; Routine SControl (StItem, NofItems, ValueBits : Integer) 
Link А6,80 
; StItem 12(A6) Start Item number 
; NofItems 10СА62 Number of Items 
; ValueBits 8CA6) Values of the items 
; Return address 4(Аб) 
; 019 Аб (Аб) 
SetControl 
GetDItem 
FontDPtr,12C(A6),Itemtupe(A4),Item(A4),ItemBox(A4) 
Cir.w 00 ; Set 00 to 1 if the item 
Lsr .W 8CA6) ; is to be set or 0 if its not. 
Bcc.s 61 
Addq.w 81,00 


61 SetCtlValue Item(A4),D0 


Addq.w 
Sub.w 
Bne.s 


Unik 
Movea. | 
Add.1 
Jmp 


FontName 


#1, 12CA6) ; Increment the item No counter. 
81, 10CA6) ; Any more items to process? 
SetControl  ; Yes -> SetControl. 


A6 

CSP )+, AD ; Pop args & return. 
"6 SP 

(Аб) 


The user has made а new selection from the Font Name 
Selection Window, either & new font name or none. TempFont 


will change. 


Bclr.b 
Beq.s 
EraseRect 
80 Move.w 
Bmi.s 
Mu lu 
Move .и 
Cmpi.w 
Beq.s 
Bset.b 
Bset.b 
Move.1 
Bra.s 
81 Move.w 
62 Bclr.b 
ӨЗ Jsr 
Window. 
GetDItem 
EraseRect 
LMUpdate 
«тр 


FontSize 


8SRect,DFlags(A4) ; Erase Rect if it hasn't 


eg ; been already. 
SanpleRect(A4) 

NameCelltv(A4),D8  ; Update the font number in 
61 ; TempFont with the number 
86,00 ; ОҒ the font selected . 
2CA3,D0 .W), TempFont (A4) 

80 TempSizeCA4) 

62 


80kActive,DFlags(A42; selections are valid. 
8SUpdate,DFlagsCA4) ; Window requires updating. 
Ticks, SampleTicksCA4) 

e3 

8-], TempFontCA4) ; No Font Name is selected. 
8OkActive,DFlags(A4); selections aren't valid. 
LdSizes ; Update Font Size Selection 


FontDPtr,* 19, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
ItemBoxCA4) 

VisRgn(A4),SizeListHCA4) 

WaitOk 


The user has made a new selection from the Font Size 
Selection Window, either a new font name or none. TempSize 
might not change. 


Move.w 
Move.w 
Вті.5 
Mulu 
Move.w 
Lea 
Move.w 


TempSizeCA4),D2 ; Store for comparison later. 
NameCe11*vCA42,D0 

eo ; No Font Мате selected. 

86,00 


2*4(A3,D0.W5),00 ; Offset to font's size list. 
САЗ,00.М), Ад ; Address of the size list. 
SizeCell*vCA42,D0 
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Bni.s 80 ; No Font Size selected. 
Lsl.w 81,00 


Move.w 2CA0,D0 .WD, TempSizeCA4); Store new font size. 
Стр.м TempSizeCA4),D2 ; Hes the size altered? 


Beq.s 80 ; № -> eg 

Jsr SetEditSize ; Update the textedit window. 
00 Jmp WaitOk 
GetEditSize 


Convert the text in the font size text edit window into a 
number to update TempSize. TempSize might not have changed, if 
the mouse is clicked within the font size text edit window 
this routine is called. 


GetDItem FontDPtr, #20, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
GetIText ItemCA4), thenameCA4) 


Lea thenameCA4), Аб 

-Str ingToNum 

Cmpi.w 84 00 

Bit 62 ; if «4 

Cmpi.w 8127,00 

Bgt 62 ; if 2127 

Стр .w TempSizeCA42,D0 ; Has the size altered? 
Beq.s 81 ; № -> 61 

Move.w 00, TempSizeCA4) ; Yes -> update TempSize. 
Cmp.w 8-1 TempFontCA4) ; Is there а valid font name? 
Beq.s e3 ; No -> 63 


Bset.b 80kActive,DFlags(A4); selections are valid. 
Bclr.b 8SRect,DFlags(A4) ; Erase Rect if it hasn't 
Beq.s eo ; been already. 
EraseRect SampleRect(A4) 

60 Bset.b "SUpdete,DFlagsC(A4) ; Window requires updating. 
Моуе. ] Ticks, Запр1еТ1ск$(А4) 

61 Jmp WaitOk 


02 Clr.w TempSizeCA4) ; Indicete its outside limits. 
63 Bclr.b ®OkActive,DFlags(A4); selections aren't valid. 
Bclr.b "SRect,DFlags(A4) ; Erase Rect if it hasn't 


Beq.s 84 ; been already. 
EreseRect SampleRect(A4) 

64 Jmp WaitOk 

FontSample 
Jsr SampleWindow ; update the attributes 


TEUpdate SampleRect(A4),Sample(A4) 

Bclr.b 8SUpdate,DFlagsCA4) ; Window has been updated. 
Bset.b BSRect,DFlags(A4) ; Sample Rect isn't blank. 
Jnp WaitOk 


SetEditSize 


Setup the font size text edit item. To access this routine 
there must be а valid font name. 


GetDItem FontDPtr,320, ItemtypeCA4), ItemCA4), I temBoxCA4 ) 
Cir. D7 

Move .w TempSizeCA4),D7 

Cmpi.w 84 DT 


Blt 61 ; if «4 
Cmpi.w 8127,07 
Bgt e1 ‚ df» 127 


Bset.b 8SOkActive,DFlagsCA42; selections ere valid. 
Bclr.b 8SSRect,DFlags(A4) ; Erase Sample if it hasn't 
Beq.s 80 ; been already. 
ЕгазеКес{ SampleRect(A4) 

80 Bset.b tSUpdate,DFlagsC(A4) ; Window requires updating. 
Моуе.1 Ticks, SampleT icks(A4) 
Lea {Пепате(А4), A0 ; Load thename pointer. 
Моуе.1 07,00 
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-NunToStr ing 


Моуе.1 Item(A4),-(SP) ; Set the item text to the new 
Моуе. ] AB, -CSP) ; number string. 
-SetIText 
Move.1 FontDPtr,-CSP) 
Move.w 820,-(ӨР) ; Select complete text in the item. 
Move.w 80,-CSP) 
Move .w $255 -(SP) 
-SellText 
Rts 

61 Cir.w TempSizeCA4) ; Indicate it's outside limits. 
Bclr.b 80kActive,DFlagsCA4); selections aren't valid. 
Bclr.b 8SRect,DFlags(A4) ; Erase Sample if it hasn't 
Beq.s 82 ; been already. 
EraseRect SampleRect(A4) 

62 Rts 

LdNames 


ListHandle): Integer 

Subq.1 82 /5Р 

Move .w (A3),-CSP) ; The number of font names - 1. 

Move.w #9 ,-(SP) 

Move. 1 NeneListHCA4), - CSP) 

-LAddRow 

Addq. 1 $2 SP 

Clr.w 07 ; Loop counter (the # of fonts -1). 
80 Move.w 07,06 

Mulu 16,06 ; Point to the next font info. 

Move.w 2(A3,D6.W),D8 ; Obtain the font's number. 

Cmp.w TempFontCA4),D8 ; Is this font to be selected? 

Bne.s e1 ; No -> 61. 

Move.w D7,NemeCell*vC(A4)  ; cell * into NemeCell*v. 
61 Move.w 2+2(A3,D6.W),D6 ; Obtain the font's name offset. 


; Load the NameList with the font names stored in FontMap. 


; Function LAddRow (count, rowNum: Integer; lHandle: 


; Procedure LSetCell CdataPtr: Ptr; dataLen: Integer; 


theCell: Cell; lHandle: ListHandle) 


to 


Pea 1(АЗ,06.\) ; Address of the name (string). 
Clr.w 00 

Move.b CA3,D6.W),D8 ; Length of the name. 

Move .w DO, -CSP) 

Move.w 80,-CSP) ; Cell column 8, 

Move .w D7,-CSP) ; Cell row 8, 

Move.1 NeneListHCA4), - CSP) 

-LSetCe11 

Addq.w 81,07 ; Increment the loop counter. 
Cmp .w (АЗ2,07 ; Loaded а11 font names yet? 
Ble.s eg ; № eg. 


Select the cell containing the font name which corresponds 
the font number passed to the FontDialog Routine. If the 


font number isn't associated with one of the fonts on the 
current system file then don't select any name. 


82 


Cmpi .w $-],NameCell*vCA4) ; Cell to be selected? 
Beq.s 62 ; № -> 62 
LMSetSelect "True, NemeCe11CA4) , NemeListHCA4) 


DeRefHndleNameListHCA42,A0 ; Scroll if selected cell 


Move.w visible*tbottom(A22,D6 ; isn't visible, ie 

¿the lest visible cell is 
Cmp.w NameCell*vCA42,D6 ; less than selected cell. 
Bgt.s e2 


LMAutoScroll NemeListHCA4) 


LMDoDrew *True,NameListHCA4) ; Drawing on. 
Rts 
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LdSizes 


61 


; load SizeList with font sizes of TempFont in FontMap. 


LMDoDrew #False,SizeListH(A4); Drawing off. 

LMDelRow 80,80 бігеі 15{НСА4) ; Delete all the rows. 
Move.1 "$FFFF0000 ,SizeCe11CA4) 

Move.w TempFontCA42,D4 ;The font number. 

Bni 65 ; -ve, no font number passed to FontDialog. 
Clr.w 07 ; Loop counter. 

Move.w D7,D6 

Mulu “6,06 ; Point to the next font info. 


; Compare the font number with the font number that was passed 
; to the FontDialog Routine. 


Cmp.w 2(A3,D6.W),D4  ; Match? 
Beq.s 62 ; Yes -> 82. 
Addq.w 81/07 ; Increment the loop counter. 
Cmp.w САЗ),07 ; Looked at all font numbers yet? 
Ble.s e1 ; No 1. 
Bra e5 ; Yes & no match was found. 
62 Move.w 2+4(АЗ,06.\),07 ; Offset to font size list. 
Move.w CA3,D7.W), D6 ; The number of font sizes. 
; Procedure LAddRow (count, rowNum: Integer; lHandle: 
ListHandle): Integer 
Subq.1 82 SP 
Move.w D6, -CSP) ; Number of rows to add. 
Move.w 8g, -CSP) 
Моуе.1 SizeListHCA4),-CSP) 
_LAddRow 
Addq.1 82 5Р 
Clr.w D6 ; Setup the loop counter. 
03 Move.w D6,D5 ; Create an offset within size list. 
Lsl.w 81/05 
Add.w D7,D5 ; Offset from the start of FontMap. 
С1г.1 00 ; Clear . for NumToString. 
Move.w 2€A3,D5.W),D8 ; A font size. 
Стр .w Тепр5іге(А42,00 ; Is this the selected size? 
Bne.s 04 ; № -> 64. 
Move.w D6,SizeCell*v(A4) ; Store cell number to select 
64 Lea thenameCA4), Ad 
-NumToStr ing 


; Procedure LSetCell CdataPtr: Ptr; dataLen: Integer; 


theCell: Cell; lHandle: ListHandle) 


to 


Pea 1(А0) ; Address of the Size (string). 
Clr.w 00 

Move.b (A02),D00  ; Length of the Size. 

Move.w DO, -CSP) 

Move.w 80,-(SP) ; Cell column #8. 

Move.w 06,-С5Р) ; Cell row 8. 

Move. | SizeListHCA4),-CSP) 

-LSetCe11 

Addq.w 81,06 ; Increment the loop counter. 
Стр.м (A3,D7.W2,06 ; Loaded all font sizes yet? 
Blt.s e3 ; No » 63. 


Select the cell containing the font size which corresponds 
the font size passed to the FontDialog Routine. If the 


font doesn't have the size selected, do nothing. 


Cmpi.w 8-],SizeCell*vC(A4) ; Cell to be selected? 
Beq.s 5 ; № -> 65 
LMSetSelect ЗТгие,5ігеСе11(А4),512е1 15%Н(А4) 


DeRefHndleSizeListHCA42,A0 
; Scroll if the selected cell isn't 


Моуе. ] (Аб), Аб ; Visible, ie lest visible cell is 

Move.w visible*bottomCA22,D6 ; less than selected 
cell. 

Cmp.w бігеСе11%У(А42,06 

Bgt.s 65 
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LMAutoScroll SizeListHCA4) 


DNu11 
65 LMDoDraw  "'True,SizeListHCA4) ; Drawing on. GetDItem 16САб), #20, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
Rts GetMouse loc_ptCA4) 
PtInRect loc_ptCA4),ItemBoxCA4) ; Was mouse within the 
Move .b (SP )+,00 ; FontSize text edit Rect? 
samp leWindow Beq.s е? ; Yes -› iBeam cursor. 
; Update the sample TextEdit Record with the currently 
; Selected font attributes. Move.1 TextCursorCA4), АВ 
Btst.b "S0kActive,DFlagsCA4); Are the selections valid? Моуе. 1 (A0), -CSP) 
Beq 80 ; № -> 80 -SetCursor 
TextFont TempFontCA4) ; Font number Bra 61 
TextFace TempFaceCA4) ; Font style 60  InitCursor ; No -> Arrow cursor. 
TextSize TempSizeCA4) ; Font size 
GetFontInfo  infoCA4) 61 Моуе.1 Ticks,D0 ; И KeyTresh Тіске have passed 
Sub. 1 Ѕатр1еТіскѕСА4),00 ; since last item alteration, 
DeRefHndleSample(A4), AQ Cmp.w KeyThresh,D8 ; update the sample window by 
Move .w TempFont(A4), teFont(AS) ; teFont Bit DFReturn ; indicating item 821 was hit. 
Move .b TempFace* 1(А4),(еҒасе(Ай) ; teFace Btst.b ®SUpdate, DF lagsCA4) 
Move.w TempSizeCA4), teSizeCAd) ; teSize Beq DFReturn 
Move.w infotascentCA4D, teAscentCAQ) ; teAscent 
Move.w info*ascentCA4)2,D0 ; teLineHite Move.w 821,00 ; Set the itemNo to 21, Semple 
Add.w infotdescent(A4),Dd Bra DF TReturn 
Add.w infotleadingCA4), DB 
Move.w DØ, teLineHiteCAd) 
Move. 1 teViewRect+topLef tCA2), teDestRect*topLef tCA2) DMouseDown 
Move. | teViewRecttbotRight(Ad), teDestRect*botRightCA2) Bclr.b "SSKey,DFlags(A4) ; Not а SKey event. 
Mulu (емі inesCA2) ,00 ; Height of the sample text. ; Obtain the (events) mouse location and convert it to 
Move.w SampleRecttbottomCA42,D1 ; local coordinates. 
Sub.w SampleRect*topCA42,D1 Move.1 evtMouseCA2), loc-pt (A4) 
Cmp.w 00,01 ; Sample greater than Rect? GlobalToLocal loc-ptCA4) 
Ble 80 ; Yes -> 80 
Sub .w 00,01 ; Center the sample ; Check to see if the mouse was clicked inside one of the 
Lsr.w 81/01 ; lines in the middle ; active rectangles. 
Add.w 01, teDestRectttopCAS) ; of SampleRect. 
80 Rts Item9 
, mouse was pressed down within item № 9? (Style heading) 
GetDItem FontDPtr,*9,ItemtypeCA42, ItemCA4), ItemBox(A4) 
= Modal Dialog User Filter ---------- PtInRect loc_ptCA4), ItemBoxCA4) 
DUserF ilter Move.b (SP)+,D8 ; Was the point within the heading? 
Beq.s Пеп4 ; No -> check item No 14's Rect. 
Link А6,80 | 
; Boolean result 20(A6) ; Routine TrackHeading CtheDialog: DialogPtr; itemNo: 
; Dialog (window? pointer 16CA6) Integer): Boolean 
; Address of the event record 12СА6) Subq.1 82, SP ; Set up for the result. 
; Addr of word to fill in item no8CA6) Move.1 FontDPtr,-CSP) 
; Return address 4CA6) Move.w 89 ,-(SP) 
; 019 Аб (Аб) Bsr TrackHeading 
Move.b (SP)*,D0 ; Wes the mouse up within the item? 
Use the event number as an index into the DEventTable. Beq SetoNull ; No, Convert event to null & return 
These 12 events are all the things that could spontaneously 
happen while the program is in the Modal Dialog event loop. Move.w 89 Dg ; Yes, return True & the item No 9. 
Bre DFTReturn 
Movea.1 16(А62,А4 ; Font Dialog Вафа Record. 
Move.w 8False,20(A6)  ; Set function result to False. Item14 
Movea.1 12С(ҮХҠ6),А0 ; Event Records Address. ,mouse was pressed down within item No 14? (Spacing heading). 
Move.w evtNunCA2),DO — ; Get the event number. GetDItem FontDPtr,* 14, ItemtypeCA4), ItemCA42, ItemBoxCA4) 
Lsl.w 81,00 ; *2 for table index. PtInRect loc_ptCA4), ItemBoxCA4) 
Move.w DEventTableCD0.W2,D0; Point to the routine offset Move.b (SP)+,D8 ; Was the point within the heading? 
Јер DEventTableCDO.W) ; and jump to it. Beq Item17 ; № check item No 17's Rect. 
DEventTable Subq. 1 82 5Р 
Dc.w  DNull-DEventTeble ; Null Move.1 FontDPtr,-CSP) 
Dc.w  DMouseDown-DEventTable ; Mouse Down Move.w 814,-CSP) 
Dc.w  DFReturn-DEventTeble ; Mouse Up (Not used) Bsr TreckHeading 
Dc.w  DKegDown-DEventTeble ; Key Down Move.b (SP)*,DO ; Was the mouse up within the item? 
Dc.w  DFReturn-DEventTeble ; Key Up (Not used) Beq SetoNull ; No, Convert event to null & return 
Dc.w DKeyDown-DEventTable ; Auto Key 
Dc.w DUpdate-DEventTable ; Update Move .w 814,00 ; Yes, return True & the item № 14. 
Dc.w DFReturn-DEventTable ; Disk (Not used) Вга DF TReturn 
Dc.w  DActivete-DEventTable ; Activate 
Dc.w DFReturn-DEventTable ; Network (Not used) Iten17 
Dc.w DFReturn-DEventTable ; 1/0 Driver (Not used) ; mouse was pressed down within item No 17? 
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; The Font Мате Selection Window. 


GetDItem FontDPtr,* 17, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
Addi .w #15, ItemBoxtright(A4) ; include vertical scroll 


PtInRect loc_ptCA4), ItemBoxCA4) 
Move .b (SP)+,D8 ; Was the point within the rect? 
Beq Item 19 ; No -> check item No 19's rect. 


If a new selection is made return true and the item number, 


otherwise set the event to a null event and return. 


; Function LClick (pt: Point; modifiers: Integer; lHandle: 


ListHandle): Boolean 
Subq.1 82 SP 
Move.1 loc-ptCA4)2, -CSP) 
Моуев.!  12(Аб), АО 
Move.w evtMetaCA0), -CSP) 
Моуе. ] Мате! istHCA4),-CSP) 
-LClick 
Addq.1 82 5Р 
С1г.1 ТетрСе11(А4) 
LMGetSelect "True, TempCel1(A4),NameListHCA4) 
Move .b (SP)+,D8 ; Is there a selected cell? 
Bne eo ; Yes -> eg. 
Move.1 "$FFFF2000,TempCe11CA4); No set TempCell to 0,- 
1; 
ed Моуе.1 Тетрбе11СА4),00 ; Has the selected cell changed? 
Cmp.1 МатеСе11(А4), DØ 
Вед SetoNu11 ; No -> SetoNull. 
Move.1 DO,NameCellCA4) ; Yes, return True & item No 17. 
Move.w 817,00 
Вга DFTReturn 
Item 19 


; Check to see if the mouse was pressed down within item No 
19 


; The Font Size Selection Window. 


GetDI tem 
Addi.w 
PtInRect 
Move.b 
Вед 


FontDPtr, #19, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
815, ItemBoxtr ight(A4) 

loc_ptCA4), ItemBoxCA4) 

(SP)+,D8 ; Was the point within the rect? 
DFReturn ; № -> DFReturn. 


If а new selection is made return true end the item number, 


otherwise set the event to & null event and return. 


Subq.1 82 ‚ЭР 
Моуе. 1 loc_ptCA4),-CSP) 


Моуев.1 12СҮ62,А0 
Move.w evtMetaCAQ), - CSP) 
Move.1 SizeListHCA42,-CSP) 
-LClick 
Addq. 1 82 /5Р 
С1г.1 TempCell(A4) 
LMGetSelect True, ТетрСе11СА4), SizeL istHCA4) 
Move.b (5Р2%,00 ; Is there а selected се11? 
Әле ед ; Yes -> 00. 
Моуе.1 S$FFFF0000,TempCellCA4) 
80 Move.1 TempCe11CA42,00 ; Hes selected cell changed? 
Cnp.1 SizeCe11CA42,00 
Beq SetoNul] ; № -> SetoNull. 
Move. | 00,5ігеСе11(А4) ; Yes, return True & item No 19. 
Move .w “19,00 
Вга DFTReturn 
DKeyDown 


Examine the key thet was pressed, if it wes a 'cr' or 


'enter' then that is equivalent to clicking the Ok button. 


Move.1 evtMessageCA0),D0 
Cmpi.b 8crCode,DÓ ; Wes the cr key pressed? 
46 


Beq.s 61 ; Yes -» 61. 
Cnpi.b SfenterCode,DÜ ; Was the enter key pressed? 
Bne.s ; № -> 62. 

61 Move.w 81/00 ; Set the item № to Ok button. 
Bre DFTReturn ; Item No 1 - Ok. 

e2 ; 


If the key pressed was the back space key or а number then 


deselect the cell in the Font Size Selection Window Cif there 
is one selected), then return, allowing the number or 'bs' to 
be used to alter the FontSize 


; text edit dete. 
Cnpi.b *bsCode, D8 
Beq.s @3 

Cmpi .b #$30 ,00 
814.56 NameSearch 
Cnpi.b #$39 ,00 
894.3 NameSearch 


; Was the bs key pressed? 
; Yes 83. 


63 Bclr.b #SKeu,DF1ags(A4) ; Not a SKey event. 
Стрі.1 *$FFFFO000,SizeCel1(A4); If а cell is selected, 
Веда — DFReturn ; deselect it, 
LMSetSelect "False,SizeCel1(A4),SizeListH(A4); let the 

; defeult routine 
Move.1 89ҒҒҒҒ0000,5і2еСе11(А4); handle the event. 
Bre X DFReturn 

NameSearch 
Lea search(A4),A2 
Bset.b tSKey,DFlags(A4) ; Was lest event a SKey event? 
Beq.s 80 ; No -> 00 
Моуе. 1 еуіТіске(А02,01 ; Yes -> If this key down 
Sub.1 SampleTicksCA42,D1 ; within KeyThresh Ticks 
Cmp.w KeuThresh,D1 ; continue the search 

string 
Blt.s e1 ; else, reset search 

string. 

eg Cir.b (А2) ; Continue. 

01 Addq.b 81 (A2) ; Reset. 

Move.1 evtTicksCA2), SampleTicksCA4) 

Clr.w D1 ; И search string is greater than 
Move.b (А22,01 ; 32, SetoNull. 

Cnpi.b 831,01 

Bgt SetoNu11 

Move.b D0,CA2,D1.w) ; Add cher to string. 
DeRefHndleFontMap(CA5), АЗ 

Clr.w 07 ; Set loop counter. 

62 Move.w 07,06 
Mulu 86,06 ; Offset to next font info. 
Move.w 2*2CA3,D6.w2,D6 ; Offset to name string. 


; Function IUMagString CePtr, bPtr: Ptr; eLen, bLen: 


Integer): Integer 


e3 


Subq. 1 82 /5Р 
Реа 1(A3,D6.w)  ; Address of FontName string. 
Pea 1(А22 ; Address of search string. 
Clr.w 00 
Моуе. 6  (A3,D6.w2,D0 
Move.w DØ, -CSP) ; Length of FontName string. 
Move.b (А22,00 
Моуе.и  D0,-(SP) ; Length of search string. 
-IUMagStr ing ` 
Move .w (SP)*,D0 ; Was the FontName =) ? 
Bpl.s e3 ; Yes -> 63 
Addq.w 81,07 ; Have а11 the fonts been 
Cmp.w (АЗ2,07 ; looked at? 
Bit 62 ; No -> 62 

; Is the desired cell selected? 


; Yes -> Don't do anything. 
; № -> Deselect existing cell & select new cell. 
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Стр.м NameCe11*vCA42,D7 

Beq SetoNu11 

LMSetSelect "False, NameCe11CA4)D,NameL istHCA4) 
Move .w 07,МәпеСе11%у(А4) 

LMSetSelect #*True,NameCel1(A4),NameListH(A4) 


DeRefHndleNameListHCA4), Ad ; If selected cell isn't 


Cmp .w visible+top(A0),D7 ; visible then AutoScroll. 
Blt.s 64 ; else continue. 
Cmp.w visible*bottomCA22,D7 
Blt.s e5 
64 LMAutoScroll NameListHCA4) 
85 Move.w 817,00 
Вга DFTReturn 
DUpdate 
Bclr.b 8SKeu, DF lagsCA4) ; Not а SKey event. 
SetPort FontDPtr 
BeginUpdate FontDPtr 


DrawControls FontDPtr 


; Update itemNo 1 


; The BoldBox around the Ok button. 


GetDItem FontDPtr, #1, ItemtypeCA4), ItemCA4), ItemBox (A4) 
InsetRect ItemBox(A4), 8-4, 8-4 

PenSize 83,83 

FrameRoundRect — ItemBox(A4),11 16,1 16 

_Реп№ гта] 


; Update itemNo 3 


; Тһе Static Text heading "Character Font & Attributes". 


GetDItem FontDPtr, #3, ItemtypeCA4), ItemCA4), ItemBox(A4) 
GetIText ItemCA4), thenameCA4) 

Lea thename(A4),A@ ; Address of the text. 

С1г.1 00 

Move.b (Аб)+, 06 ; Length of the text. 
TextBox — A2,D0, ItemBox(A4), tg 


; Update the Font Style Selection Window 


; Тһе ThinBox around the Style Check Boxes Citem No 10). 


GetDItem FontDPtr,* 10, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
FrameRect ItemBoxCA4) 

; The Static Text heading "Style" Citem No 9). 

GetDItem FontDPtr,#9 ItemtypeCA4), ItemCA4), ItemBox(A4) 
GetIText  ItemCA4), (һепапе(А4) 

Lea thenameCA4),AQ ; Address of the text. 

С1г.1 00 

Move.b (A0)*,D0 ; Length of the text. 

TextBox А2,00, ItemBoxCA4), 80 


; Updete the Font Spacing Selection Window 


; Тһе ThinBox around the Style Check Boxes Citem No 15). 
GetDI tem FontDPtr, #15, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
FrameRect ItemBoxCA4) 


; Тһе static text heading "Spacing" Citem No 14). 


GetDItem FontDPtr, #14, ItemtypeCA4), ItemCA4), ItemBox(CA4) 
GetIText ItemCA4), thenameCA4) 

Lea thenameCA4), Ad ; Address of the text. 
Cir. 00 

Move.b САЙ )+, DO ; Length of the text. 
TextBox А0,00, ItemBoxCA4), #0 


; Update itemNo 16 


; The Static Text heading "Font Name:". 

GetDItem FontDPtr, #16, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
GetIText ItemCA4), thenameCA4) 
Lea thename(A4), AQ 

Cir. 00 

Move.b (A0)*,D0 


; Address of the text. 


; Length of the text. 
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TextBox — A0,D0, ItenBox (A4), #0 


; Update itemNo 17 


2 


д 


; Тһе Font Name Selection Window. 


GetDItem FontDPtr, #17, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
InsetRect ItemBox(A4), #-1, 8-1 

EraseRect ItemBoxCA4) 

FrameRect ItemBox(A4) 

LMUpdate VisRgnCA42, NameL istHCA4) 


; Updete itemNo 18 


; The Static Text heading "Font Size:". 


GetDItem FontDPtr,* 18, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
GetI Text  ItemCA4), thenameCA4) 

Lea thename(A4), Ad ; Address of the text. 
Clr. 00 

Move.b (А+, DØ ; Length of the text. 
TextBox А0,00, ItemBox(A4), #0 


; Update itemNo 19 


; Ihe Font Size Selection Window. 


GetDItem FontDPtr, #19, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
InsetRect ItemBox(A4), 8-1, 8-1 

EraseRect ItemBoxCA4) 

FrameRect ItemBoxCA4) 

LMUpdate VisRgn(A4),SizeListHCA4) 


; Update itemNo 20 


4 


; The TextEdit text item. 


GetDItem FontDPtr , #20, ItemtypeCA4), ItemCA4), ItemBoxCA4) 
EraseRect ItemBoxCA4) 

TEUpdate ItemBoxCA4), teHandleCA4) 

InsetRect ItemBox(A4), 1-3, #-3 

FremeRect ItemBoxCA4) ; Frame the textedit item. 


; Update itemNo 21 


; Update the Sample Text Window. 
EraseRect SampleRect(A4) 


Bclr.b 8SRect,DF1ags(A4) 
Btst.b 80kActive,DFlagsCA4); Are selections valid? 
Вед . 80 ; No -> eg 
TEUpdate SampleRect(A4),SampleCA4) ; Yes -> update sample 
Move.1 Ticks,SampleTicksCA4) ; and associated 
Bclr.b ®SUpdate, DF lags(A4) ; variables. 
Bset.b ®SRect, DF lagsCA4) 
80 EndUpdate FontDPtr 
Bre Se toNul 1 
DActivate 


Check first to see if this activate event is associated 


with this Dialog Window, compare the Dialog Window's pointer 


to 


that of the Window pointerin the event record. Ай contains 


the address of the event record. 


Move. | FontDPtr , 06 

Cmp.1 evtMessageCA0),D0 

Bne DFReturn ; Event not related to Dialog. 
Bclr.b RSKey,DFlags(A4) ; Not a SKey event. 

SetPort — FontDPtr 

Movea.1 12(Ү6),А0 ; Address of the event record. 
Move.w еу Ме(а(А02,00  ; Obtain the modify word. 

Lsr 81,00 ; Check Bit 0 to see if its 
Bcc DDeactivate ; Activate or Deactivate. 
TEActivate — teHandleCA4) 


LMActivate® True, Мате istHCA4) 
LMActivate® True, SizeListHCA4) 
Bra SetoNul] 


DDeactivate 
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TEDeactivate teHandleCA4) 
LMActivate*False, NameL istHCA4) 
LMActivate*False,SizeListHCA4) 


Bra SetoNu11 
SetoNu11 
Movea.1 12С(Ү62,А0 ; Obtain the address of the Event 
Clr.w evtNunCA2)  ; Record & set it to a null event. 
Bra.s DFReturn 
DFTReturn 
Move.b "True, 20(A6) ; Dialog Filter (True) Return. 
Моуеа. 1 ВСАб),Аб 
Мохе .м 00,(А0) 
DFReturn ; Dialog Filter Return. 
Unlk A6 
Моуеа.1  (SPO*,A0 ; Pop ergs & return. 
Add. 1 812, SP 
«тр CAB) 
TrackHeading 
Link А6,8-22 
; Boolean result 14CA6) 
theDialog pointer 10СА62 
itemNo 8CA6) 
Return address 4CA6) 
019 Аб (Аб) 
Temporary Region Handle Nol -4(А6) 


Temporary Region Handle №2 -8(Аб) 


wee We We We We We We We Ve 


Vis boolean - 109CA6) 
Mouse Location -14CA6) 
Temporary Rectangle -22C(A6) 


Move.b "False, 14(A6) ; Set up to return False. 
; Get Rect of user item that surrounds the headings control 
; items (check boxes or radio buttons). 

Addq.w 81,8(А6) 

GetDItem 10(Аб),8 (Аб), ItemtypeCA4), ItemCA4), -22CA6) 


; Create а region and store the current clipping region. 
NewRgn 


Move.1 
-GetClip 


(SP2,-4(A6) ; Store the regions handle. 


Create а new clipping region which is the user item's rect 
inset by 1 pixel on 811 sides minus the intersection rectangle 


of the heading's rect and the newly created rect. 


NewRgn 

Моуе. ] (SP), -8CA6) 
InsetRect -22(А62,81,81 
-OpenRgn 

FremeRect -22(Аб) 


; Store the regions handle. 


Find the rectangle that is the intersection of ItemBox(A4) 
and -22(A6). If they intersect then remove that rectangle from 


the clipping region. 


SectRect  ItemBoxCA4), -22CA6), TempRect 
Move.b (SP)+,D0 ; Was there an intersection? 
Beq.s 61 ; No — 61. 
FremeRect TempRect 

81 _CloseRgn 
SetClip 


; hendle is already on stack. 
-8(A6) 


PenSize — 81,8] 
PenMode %10 


; Draw the rectangle in question, giving the user the 
; impression that they have selected the heading. 
FrameRect -22(Аб) 
Move.b “Тгие,-10(А6); Set the vis byte to True. 
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; Set up the new clipping region. 


; Inverts what ever is drewn over. 


Track 
StillDown 
Move.b (SP)+, DØ ; Is the mouse button still down? 
Beq 61 ; №  e1. 


GetMouse -14(Аб) 
PtInRect -14(Аб), ItemBoxCA4) 


Move.b (SP)*,D0 ; Has the mouse entered or 
Cnp.b -10(462,D0 ; left the item's rect? 
Beq.s Track ; № => Track. 
FrameRect -22(A6) ; Yes -> toggle the rectangle. 
Eori.b 81,-10(46) ; Toggle the visible byte. 
Bre.s Track 

61 Move.b -10(А6)0,00 ; Is the rect visible? 
Beq.s 02 ; № -> Return False. 
FrameRect -22(A6) ; Yes -> Remove the rectangle & 
Move.b * True, 14(А6) ; return True. 

62 _Реп№ гта] 
SetClip -4CA6) ; Reset to its original setting. 


DisposeRgn-4(A6) 
DisposeRgn-8CA6) 


; Dispose of two temporary regions. 


Unik A6 
Movea.]  (SP2*,A0 ; Pop ergs & return. 
Add. 1 86, SP 
Jmp (Ай) 
р Variables ------ 
FontDRec 08.1 1 
“Sabu ЛЕБ СЕС SetupFontMap ----------------- 


; Written by Ray.A.Cameron 
; Version 1.0 
; Mon May 4, 1988 21:41:50 


XDef SetupFontMap ; Routine's name 
XDef FontMap ; Global location for the 
FontMap's Handle 


qusc anid Includes ------------- 
Include Traps.D ; Use System and ToolBox traps 
Include PackMacs. Txt ; Use Package Equates 
оақнтентетт Equates ---------- 
Тгие Еам 1 
False Equ 0 
FNum Equ %1111111111000000 
FSize Equ %0000000000111111 
SetupFontMap 
Link А6,80 
Movem.1 (00-ОТ7/Ай-А4,-(СӨР) ; Save register values. 


; Function CountResources СіһеТуре: ResType): Integer; 
Clr.w -($Р) ; Clear for answer. 

Move.1 t 'FONT',-CSP2; Count number of ‘FONT’ resources. 
-CountResources 

б1г.1 07 

Move.w (SP)*,D7 ; Store the result. 


Create а non-relocatable block into which will be stored 


each font resource ID, if the resource has a font size Cie no 


name). 
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Моуе. 1 07,00 ; Create a size to allow 2 bytes Гог 
Ls].w 81,00 ; each resource ID. 

-NewPtr „Clear 

Movea.! А0,А4 ; Store pointer to non-relocatable block. 


Setup the Resource Manager so that the resources eren't 
loaded into memory. 


; Procedure SetResLoad (load: Boolean); 


Move.b *"False,-CSP) ; Load False 
-Se tResLoad 
Clr.w 03 Loop counter (* of font resources). 


Cir.w 04 — ; Offset into the theID non-relocatable block. 
7 


Clr.w 05 ; The number of different fonts. 
С1г.1 06 ; The 8 of bytes to allocate to FontMap. 


; Setup а non-relocatable block for the name of а resource. 


Move.1 8256,00 ; The 8 of bytes required. 
-NewPtr „Clear 
Move.1 AQ,thenameCA5) ; Store pointer. 

ExamRes 


Addq.w 81/03 ; increment loop counter. 


Obtain а handle to а resource with type 'FONT' and an index 
value from 1-to-CountResources. 


; Function GetIndResource (theType: resType; index: 
Integer): Handle; 


С1г.1 -(SP) ; Space for handle 
Моуе.1 W'FONT',-CSP) ; Font resource type 
Move.» D3,-(SP) ; Index value 

-Get IndResource 


; Use the handle to obtain the resources ID and name. 
; The handle is already on the stack. 

Pea — theID(A5) ; point to theID 

Pea — theType(A5) ; point to theType 

Моуе.1 thename(A52,-(SP)  ; load address of name 
-GetResInfo 


Move.w theIDCA5),D@ ; Examine theID to see if resource 
Andi .w "FSize,DO ; has a font size Cie no name). 
Beq.s NoS ize ; NoSize, ie а name-> NoSize 


Plece theID of the font resource (which contains a font 
size) into the non-relocateble block. Then increment the 
offset. 


Move.w theIDCA52, CA4,D4.W) 
Addq.w #2,D4 ; increment the offset 
Bra.s Testloop 
NoSize 
Movea.] (һепапе(А5),А0 


Evaluate the number of bytes to allocate to this font's name 
in the FontMap. Add this to the running total. 


С1г.1 00 
Move.b CAB), DB 
Bset.1 80,00 
Addq.1 81,00 
Add. 1 00,06 
Move.1 
Move.w 
Addq.w 


; Create ап even length for the name 
; Cie add padding if its rEquired). 


; Update the running total. 
Ай,-(ӨР) ;Place the pointer to the name and 
theIDCA52,-CSP) ; resource ID onto the stack. 


Create а new non-relocatable block for the next font 
resource name. 


Move.1 256,00  ; The * of bytes required. 
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81,05 ; Increment the number of different fonts. 


-NewPtr „Clear 

Move.1 АВ, thename(A5) ; Store pointer 
Testloop 

Cmp .w D3,D7 ; Have all font resources been 

Bne.s ExamRes ; examined, No -> ExamRes 


; Dispose of pointer іп thename(A5) 
Movea.] (һепапе(А5),А0 
-DisposPtr 


Setup the Resource Manager so that the resources can be 
loeded into memory. 


; Procedure SetResLoad (load: Boolean); 
Move.b "True, -CSP) ; Load True 
-SetResLoad 


Evaluate the number of bytes required for the FontMap. 
Then create а relocatable block for the FontMap. D6 contains 
the number of bytes to allocate for the font names in the 
FontMep. 


Addq.1 82,D6 ; 2 bytes for "the number of fonts" 
С1г.1 00 

Move.w 05,00 ; The # of different fonts, each font 
Mulu 86,00 ; list rEquires 6 bytes. 

Add.1 00,06 

Моуе.1 00,03 ; Reserved for later. 


The amount of space to allocate for the font sizes is 2 x 
the number of font resources. This allows one word per entry. 


1811 4107 
Add.| 07,06 ; Grand Total in 06 


Моуе. 1 06,00 


-NewHandle 

Моуе. 1 A®,FontMap(A5) ; Store the FontMap handle. 
Movea.1 40,42 ; Copy the handle. 

-HLock ; lock it 

Моуев.1 (А2),А2 ; Obtain the address of the FontMap. 
Subq.w 81,05 ; Тһе number of fonts- 1. 

Move.w D5,CA2) ; Store # of fonts- 1 in FontMap. 


Lea.1 2(A2,D3.W),A1; start of font name list. 
Lea. 1 2(А2),А0 ; Start of the font info list. 


; Transfer theID and name pointer onto FontMap from stack. 


Transfer 
Move.w СР 2+, САд)+ ; theID 
Мохе .1 (SP?*,CAQD* |; name pointer. 
Cnpa.1 A0,A1 ; Have all the resources been transfered? 
Bne.s Trensfer ; № > Transfer. 


; Тһе information on the FontMap, іп the font info list is 
now sorted 

; So that the first font info has the lowest Calphabeti- 
cally) name 

, associated with it. 

Move.w (А22,07 

Mulu #6,D7 
61 Move.w 07,06 
62 Subq.w 86,06 

Bmi.s ез 

Момеа. 1 2+2C€A2,D7.W),A1 ; Load pointer to aStr 

Movea.1 2+2CA2,D6.W),A@ ; Load pointer to bStr 

; Compare the two strings. 

; Function IUMagString CaPtr, bPtr: Ptr; әгеп, bLen: 
Integer): Integer; 

Clr.w -($Р) 


; Point to last entry in list 


; Clear for result. 


4 9 


Реа 1СА1) ; Address of eStr 


Pea 1(А0) ; Address of bStr 
Clr.w 00 

Move.b СА1),00 

Move.w DO, -CSP) ; Length of eStr 
Move.b CAB), DB 

Move .w D8, -CSP) ; Length of bStr 


-IUMagStr ing ; Compare aStr and bStr 
Move.w (ӘР2%,00 

Cmpi.w 81,00 ; Wes aStr greater than bstr 
Beq.s 62 ; Yes -> 8&2. 


; Swap the theID and the name pointers over 


Move.w 2(A2,07.W2,00 ; Swap theIDs over 
Move.w 2CA2,D6.W2,2CA2,D7 .W) 
Move.w D0,2(A2,D6.W) 
Move.1 2+2(А2,07.\),08 ; Swap the pointers over 
Move. 1] 2+2CA2,D6.W),2+2CA2,D7.W) 
Move. ] DO, 2+2CA2,D6.W) 
Bra.s 82 
ӨЗ Subq.w “6,07 ; Shorten the search and repeat until 
Bne.s 61 ; the table is completely sorted. 


Now that the entries in the font info list have been sorted 
the font names are loaded into the FontMap and the name 
pointer is now replaced by а two byte offset, Ав each font 
name is loaded its non-relocatable block is disposed of. 


Move.w (A22,D5 

Addq.w 81,05 ; The number of fonts. 
Mulu 86,05 

Addq.w #2,D5 


; D5 contains the offset to the postion of the first font 
name. 


Cir.w D7 ; loop counter (the # of fonts - 1) 
LoadNames 


Move .w 07,06 

Mulu 86,06 ; Point to the next font info 
Movea.] 2%2(А2,06.М0,АЗ ; Obtain pointer to the name. 
Move .w 05,2*2(A2,D6.W) ; Store name offset in FontMap. 


; Perform а BlockMove to load the font's name. 
; Procedure BlockMove CsourcePtr, destPtr: Ptr; byteCount: 


Size); 
С1г.1 00 
Move.b САЗ),00 
8зеі.1 80/00 
Айда .1 81,00 ; * of bytes required to move. 
Lea (АЗ), Аб ; load source address 


Lea (A2,05.W2),A1 ; load destination address 


Add.w 00,05 ; point to next name (offset) 
-BlockMove 

Movea.1 АЗ,Ай ; Dispose of the non-relocatable block 
-DisposPtr ; it's no longer required. 

Addq.w 81,07 ; increment counter 

Cmp.w СА2),07 

Ble.s LoadNemes 


; Loed the font sizes 


Clr.w 07 ; loop counter 
LdFSizes 
Lea (A2,05.W2,A0 
Clr.w (A0) 
Move.w 07,06 
Mulu 86,06 Point to the next font info 
Move .w 2(A2,D6.W),D3 theID of the font 


we We We We We 


Move.w 05,4+2(А2,06.\) ; size list offset in FontMap 
Clr.w D2 Offset into the theID block 
61 Move.w (A4,02 .W2,D0 Obtain the next theID 
Andi .м #FNum, DØ 
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Cmp.w 03,00 
Вле.5 62 
Move.w (А4, 02.М42,00 
Andi .w "FSize,DO 
Addq.w 81, (А0), Increment "8 of font sizes" counter 
Move.w (А0),01  ; Offset to place font size in list 
Lsl.w 81/01 ; Doubled to allow for word length. 
Move.w D0,CA0,D1.W) ; Store the font size 

62 Addq.w 12,02 ; Increment offset counter 
Cmp.w D2,D4 ; Examined the complete block 
Bgt.s ёі ; No -> 61. 


; Sort the font size list in order of smallest to largest. 


Move.w (A0),D3 ; The # of font sizes 
Lsl.w 81,03 ; Offset to the lest font size 
Sort 1 
Move.w 03,02 
Sor t2 
Subq.w 82/02 
Beq.s Sort3 
Move.w CA0,03.W2,D1 
Cmp .w (Ай,02.М42,01 
Bgt.s Sor t2 
Move.w (A0,02.W2,CA0,D3.W) 
Move.w D1,CA2,D2.W) 
Bra.s Sor (2 
Sort3 
Subq.w 82,03 
Bne.s Sort! 


; Convert the font "theID" into the font number 


Move.w 2CA2,D6.W2,D3 
Lsr.w 87,03 
Move.w D3,2CA2,D6.W) 


Update the offset in the FontMap (05) to point to the 
location of the font sizes associated with the next font. 


Move.w CAB), DB 
Addq.w 81,00 
(81.4 81,00 
Add .w 00,05 


; Check to see if there аге any more fonts to load into the 
FontMap. 


Addq.w 81,D7 
Cmp.w (А22,07 
Ble.s LdFSizes 


The FontMap has been created, and loaded with its informa- 
tion. Dispose of the theID non-relocatable block and unlock 
the FontMap. 


Moves. | А4,А0 
-DisposPtr 

Movea.1 FontMapCA52, Аб 
-HUn lock 


; Restore registers to their original values 


Movem.] X (SP2*,D0-D7/A0-A4 
Unik A6 
Rts 
eae eas Variables ---------- 
іһе 0 05.4 1 
theType 0$.1 1 
thename 06.1 1 
Ғоп (Мар 06.1 1 ; Handle of the FontMap. 
End 
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; Written by Ray.A.Cameron 
jupes Control Manager Routines 


; Procedure DrawControls (др: GrafPort) 
.Масго DrawControls 

Move.1 %1,-C(SP) 

-DrawControls 

.Endm 


; Procedure HiliteControl CtheControl: 
hiliteState: Integer) 

.Macro HiliteControl 

Move.1 %1,-CSP) 

Move .w $2, -(5Р) 

-HiliteContro] 

.Endm 


Control Handle; 


; Procedure SetCtlValue CtheControl: 
theValue: Integer?) 

.Масго SetCtlValue 

Move.1 %1,-CSP) 

Move .м %2,-СӨР) 

-SetCtlValue 

.Епдп 


ControlHandle; 


; ----- Dialog Manager Routines 


; Procedure CloseDialog CtheDialog: DialogPtr) 
.Macro CloseDialog 

Моуе. ] %1,-(ӨР) 

-CloseDialog 

.Endm 


; Procedure GetDItem CtheDialog: DialogPtr; itemNo: Integer; 
Var type: Integer; Var item: Handle; Var box: Rect) 
.Macro GetDItem 


Move.1 %1,-CSP) 
Move .w $2, -(SP) 
Pea 23 

Pea 54 

Реа %5 

-GetDI tem 

.Endm 


; Procedure GetIText Citem: Handle; Var text: Str255) 
.Macro GetIText 

Move. ] %1,-CSP) 

Pea $2 

-GetIText 

.Endm 


; Procedure SetDItem (theDialog: DialogPtr; itemNo: 
Integer; type: Integer; item: Handle; box: Rect) 
.Масго SetDI tem 


Move.1 %1,-CSP) 
Move.w %2,-(SP) 
Move.w %3,-(SP) 
Pea $4 
Реа %5 
-SetDItem 
.Endm 
y жете Event Manager Routines 


; Procedure GetMouse (Var mouseLoc: Point) 
.Macro GetMouse 

Pea $1 

_бе{Моизе 

.Епдп 
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; Function StillDown: Boolean 
.Macro StillDown 


Clr.w - (P) 
-StillDown 
.Endm 

у Sooo List Manager Routines 


; Procedure LActivate Cact: Boolean; lHandle: ListHandle) 
.Macro LMActivate 


Move.b %1,-CSP) 
Move. 1 %2,-(SP) 
-LActivate 

.Endm 


; Procedure LAutoScroll ClHandle: ListHandle) 
.Macro LMAutoScro11 

Моуе. ] %1,-(ӨР) 

-LAutoScrol] 

.Endm 


; Procedure LDelRow (count, rowNum: Integer; lHandle: 
ListHandle) 
.Масго LMDelRow 


Move.w %1,-CSP) 
Move .w %2,-(SP) 
Move. 1] %3,-(SP) 
-LDe1Row 

.Endm 


; Procedure LDispose ClHandle: ListHandle) 
.Macro LMDispose 

Моуе. ] $1,-CSP) 

_LDispose 

.Епат 


; Procedure LDoDraw (drawIt: Boolean; lHandle: ListHandle) 
.Macro LMDoDraw 


Move.b $1,-CSP) 
Move.1 82,-CSP) 
_LDoDraw 

.Endm 


; Function LGetSelect (next: Boolean; Var theCell: Cell; 
lHendle: ListHandle): Boolean 
РЕ LMGetSelect 


Clr.w -(SP) 
Move.b %1,-(SP) 
Pea $2 
Моуе.1 $3,-(SP) 
-LGetSelect 

.Endm 


; Procedure LSetSelect (setIt: Boolean; theCell: Cell; 
lHendle: ListHandle) 
.Macro LMSetSelect 


Move.b %1,-(SP) 
Move. 1 $2,-(5Р) 
Моуе. 1 $3, -(5Р) 
-LSetSelect 

.Endm 


; Procedure LUpdate CtheRgn: RgnHandle; lHandle: List- 
Handle) 
.Macro LMUpdate 


Move.1 $1,-CSP) 
Move.1 $2, -(5Р) 
-LUpdate 
.Endm 
; ----- Memory Manager Routines 
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Procedure DisposePtr (p: Ptr) Pea 21 


7 
; On Entry Ай: p (pointer) Move .w %2,-(SP) 
; On Exit A0: 0 Move.w %3,-(5Р) 
: 00: result code Cinteger) -InsetRect 
.Масго DisposePtr .Endm 
Move. 1 %1,А0 
-DisposPtr ; Function NewRgn: Коп Handle 
.Епат .Macro NewRgn 
С1г.1 -(SP) 
; Procedure HLock (h: Handle) -NewRgn 
; On Entry Аб - h (Handle) .Endm 
; On Exit 00 - result code (integer) 
.Macro HLock ; Procedure PenMode (mode: Integer) 
Movea.1 21,40 .Macro PenMode 
-HLock Move.w 81,-CSP) 
.Endm _PenMode 
.Endm 
; Procedure HUnLock Ch: Handle); 
; On Entry Аб - h (Handle) ; Procedure PenSize (width, height: Integer) 
; On Exit 00 - result code (integer) .Macro PenSize 
.Масго HUnLock Move.w %1,-CSP) 
Моуеа.1 %1,А0 Move.w 82,-CSP) 
-HUnLock -PenSize 
.Endm .Endm 
p ESSE Quick Drew Routines ; Function PtInRect (pt: Point; г: rect): Boolean 
.Macro PtInRect 
; Procedure DisposRgn (гап: RgnHendle) Clr.w -CSP) 
.Macro DisposeRgn Move.1 %1,-CSP) 
Моуе. ] $1,-CSP) Pea 52 
-DisposRgn -PtInRect 
.Endm .Endm 
; Procedure EraseRect (r: Rect) ; Function SectRect (srcRectA, srcRectB: Rect; Var dstRect: 
.Macro EraseRect Rect): Boolean 
Pea %1 .Macro SectRect 
-EreseRect Clr.w -(SP ) 
.Endm Pea 21 
Pea 22 
; Procedure FrameRect (г: Rect) Pea 23 
.Macro FrameRect -SectRect 
Pea $] .Endnm 
-ҒгатеКесі 
.Endm ; Procedure SetClip (rgn: RgnHandle) 
.Macro SetClip 
; Procedure FrameRoundRect Move. | %1,-(ӨР) 
.Масго FrameRoundRect -SetClip 
Pea 41 .Endm 
Move .w %2,-(SP) 
Move .w 83,-(SP) ; Procedure SetPenState (pnState: PenState) 
-FremeRoundRect .Macro SetPenState 
.Епдп Реа 21 
-SetPenState 
; Procedure GetFontInfo (Var info: FontInfo) .Endm 
.Масго GetFontInfo 
Pea 51 ; Procedure SetPort (gp: GrafPort) 
-GetFontInfo .Масго SetPort 
.Endm Move. | %1,-CSP) 
-SetPort 
; Procedure GetPenState (Var pnState: PenState) .Endm 
.Macro GetPenState 
Pea 21 ; Procedure TextFace (face: stlye) 
_GetPenState .Macro TextFace 
.Endm Move .w %1,-(SP) 
_TextFace 
; Procedure GlobalToLocal (Var pt: Point); .Endm 
.Macro GlobalToLocal 
Pea £1 ; Procedure TextFont (font: Integer) 
_GlobalToLocal .Macro TextFont 
.Endm Move .w %1,-CSP) 
_TextFont 
; Procedure InsetRect (Var r: Rect; dh,dv: Integer) .Endm 


.Масго InsetRect 
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; Procedure TextSize (size: Integer) 
.Macro TextSize 

Move.w £1,-CSP) 

-TextSize 

.Endm 


p US Resource Manager Routines 


; Function GetResource (theType: ResType; theID: Integer): 
Handle 

.Macro GetResource 

С1г.1 -CSP) 

Move.1 821,-CSP) 

Move .w $2,-(SP) 

-GetResource 

.Endm 


саа Text Edit Routines 


; Procedure TEActivate (ҺТЕ: TEHandle) 
.Масго TEActivate 


Моуе.1 $1, -(3Р) 
-TEAct ivate 
.Endm 


; Procedure TEDeactivate СҺТЕ: TEHandle) 
.Масго TEDeactivate 


Моуе. ] %1,-(5Р) 
_TEDeactivate 
.Endm 


; Procedure TEDispose СҺТЕ: TEHandle) 
.Macro TEDispose 

Мохе .1 %1,-CSP) 

-TEDispose 

.Endm 


; Procedure TEUpdate (rUpdate: Rect; hTE: TEHandle) 
.Macro TEUpdate 


Pea $1 
Move.1 %2,-(SP) 
_ТЕУрда{е 

.Endm 


; Procedure TextBox (text: Ptr; length: LongInt; box :Rect; 
j just: Integer) 
.Macro TextBox 


Move. | $1,-(5Р) 
Move. 1 82,-CSP) 
Pea $3 
Моуе. м %4,-(SP) 
-TextBox 
.Епат 
jew Window Manager Routines 


; Procedure BeginUpdate (др: GrafPort) 
.Macro BeginUpdate 


Моуе. 1 %1,-(SP) 
-BeginUpdate 
.Endm 


; Procedure EndUpdate (WindowPtr: WindowPtr) 
.Macro EndUpdate 

Моуе. 1 %1,-(ӨР) 

_ЕпдУрда{е 

.Endm 


; Procedure HideWindow CtheWindow: WindowPtr) 
.Macro HideWindow 


Move. | %1,-(SP) 
-HideWindow 
.Endm 
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; Procedure ShowWindow CtheWindow: WindowPtr) 
.Macro ShowWindow 


Move.1 %1,-(SP) 
-ShowWindow 
.Endm 
нана Miscellaneous Routines 
.Macro DeRefHndle 
Моуеа. 1 521,32 
Моуеа. 1 (322,82 
.Endm 


; File Window.L ink 
IStaert 

/Output Window 

[ 


FontMap 
FontDialog 
Window 


/Include Window.Rsrc 


* Window.R 
* resource file for the program called "Window" 
x 


Window .Rsrc 


q ° q ° é ó э э 


Tupe RACA = STR 


0 
7 
9 by Ray А. Cameron of Australia \20уег 4 MAR 1988 


Туре FREF 
, 128 

APPL 0 

, 129 

TEXT 1 


Tgpe BNDL 

, 128 

RACA 0 

ICN! 

0 128 1 129 
FREF 

0 128 1 129 


* bit 15 
* bit 14 
* bit 13 


Switcher save screen 

accept suspend resume events 
Switcher enable option switch 

* bit 12 = can do background on null events 

* bit 11 = multifinder aware 

x (activates & deactivates topmost 

x window at resume, suspend events) 


Type SIZE - GNRL 
=] 


2 


‚Н 

4800 ;; $4800 = bits 14,11 set 
L 

128000 ;; (for 150К recomended) 

4 
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80000 ;; (for 80K minimum) 
“A 


x 


* MENU Resource 81 specifies the menus used by the Window 
program. 

* For proper support of the Desk accessories, the Apple menu 
* should be first, and the Edit menu should be third. The 
first 5 items 

* in the Edit menu should be identical to those used below. 
This makes 

* it possible for the desk accessories to share the Edit menu 
with your 

* application. 

x 


Type MENU 
‚1 (16) 
MA 
About This Exemple... 
(- 


Quit/Q 


‚3 (16) 
Edit 
(Undo/Z 


‚4 (16) 
Font 
Dialog../F 


* Dialog Resource #1 specifies properties of the About box. 
It points 

* to Dialog Item List (DITL) Resource 81 as containing its 
items. 


Туре DLOG 
‚1 


100 100 190 400 
Visible NoGoAway 
1 

0 

1 


* Dialog Resource 8260 specifies properties of the Font box. 
It points 

* to Dialog Item List (DITL) Resource 8260 as containing its 
items. 


,260 
This is the Font Modal Dialog. 
30 38 330 473 
Invisible NoGoAway 
1 
0 
260 


* Alert Resource 8260 specifies properties of the Font Alert 
box. It points 

ж to Dialog Item List (DITL) Resource #261 as containing its 
items. 


Type ALRT 
,260 
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30 38 100 473 
261 
6665 


х Dialog Item List Resource #1 specifies the items in the 
About box. 

* By convention, the first item in ап item list is the OK 
button. 

* [f there is а cancel button, it should be second. This 
makes it 

х easier to interpret the item number returned by the call to 
ModalDialog. 


Туре DITL 


2 


Button 
60 230 80 290 
OK 


StaticText 
15 20 36 300 
This sample program was written 


StaticText 
35 20 56 300 
just to prove it could be done! 


ж Dialog Item List Resource 8260 specifies the items in the 
Font box. 

,260 
21 


button 
8 359 26 427 
Ok 


button 
8 281 26 349 
Cancel 


staticText Disabled 
4 4 18 194 
Character Font & Attributes 


checkBox 
63 339 79 422 
Bold 


checkBox 
19 339 95 422 
Italic 


checkBox 
95 339 111 422 
Underline 


checkBox 
111 339 127 422 
Outline 


checkBox 
127 339 143 422 
Shadow 


staticText 
45 339 61 375 
Style 


userItem Disabled 
53 331 151 427 
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radiobutton 
95 235 111 318 
Normal 


radiobutton 
111 235 127 318 
Condense 


radiobutton 
127 235 143 318 
Extend 


staticText 
77 235 93 288 
Spacing 


userItem Disabled 
85 227 151 323 


staticText 
34 4 48 81 
Font Name: 


userItem 
54 5 150 126 


staticText 
34 151 48 218 
Font Size: 


userItem 
54 152 150 186 


editText 
34 226 48 261 


userItem Disabled 
158 4 293 427 


,261 
2 


button 
8 359 26 427 
Ok 


staticText Disabled 
25 91 61 328 
Please select а font “07172 


* WIND Resource 81 specifies the title, coordinates, and other 
status 

* for the window in which editing takes place. It is dis- 
played by a 

* call to GetNewWindow. 


Type WIND 
1 


A Sample 

50 40 300 450 
Visible МобоАмау 
0 

0 


х STR Resource 8261 to 8263 аге the strings associated with 
* the Font Alert box. Informing the user es to the invalid 
information. 


* Resource 8264 is the sample text displayed at the bottom of 
the 


* Font Modal Dialog Box. 


Type STR 
,261 


size between 4 and 127 


end a font 
, 264 
ABCDEFGHIJKLMNOPQRSTUVWXYZM2D* * 
abcdef ghi jklmnopqrstuvwxyz VD* * 
1234567890 (00% 57 
18% ӘС) е) 
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Assembly Lab 


Faster Bitmap Rotation 


Faster Bitmap Rotation Optimizing 
By Tuning Assembler Code 
Mike Morton, University of Hawail 


In last February's MacTutor, John Olsen showed a routine 
which copied one bitmap to another — and rotated it 90?. For 
speed, John coded his rotation routine in assembler. 

Maybe it's the effect of working in 68000 assembler for the 
last couple of years, or maybe I’m just being ornery, but I noticed 
a few things I wanted to try to speed up. John put it best when he 
said “Маке your code do the bare minimum first, then, after it is 
working, enhance it." 

In this article we'll try to enhance the speed of John's 
rotation routine. If bitmap rotation isn't your cup of tea, you may 
want to read along anyway — the lessons of tight assembler code 
are applicable to many other problems. 

Also, if you didn't follow every detail of John's writeup, 
don't worry — I didn’t either. One approach to optimizing code 
is to look at what it does, not what it's trying to do, then change 
itto do the same thing faster. Most of the optimizations I found 
could have been found even if I didn't know exactly what the 
routine was doing. 


Getting a Baseline 

To start with, let's do some preliminary cleanup and find out 
just how fast the routine is. There are a couple of NOP instruc- 
tions in the inner loop of the on-disk copy (they're not in the 
magazine version; I'm not sure why...) which we can ditch. 

Then there are some unused labels. They're an interesting 
way to document points in assembler code, but I think they clutter 
things up when you're looking for speed. It's very important to 
know what the flow of control is. The removable labels are: 
computeInitLowerLeft, doneWithSrcWord, doneWithRow, 
doneWithDestWord, and cleanUpTime. 

Now let's put in some timing. We won't be concerned with 
perfect accuracy, so the “tick count" will do fine. We'll add а 
local variable called “‘startTime” to the other local variables. 
Then, at the beginning of the routine, add: 

move.] ticks, startTime-localVars(ad) 

to strobe the starting time. At the end, just before exiting, 

add: 


тоуе.1 ticks, 90 
sub.| сізгіТіпе-1оса1Уагв(г0), 40 


-Debugger | 
This gets the final time, computes the elapsed time, and 


drops into the debugger so I can see the elapsed time in register 
DO. 

An easier way would be to compute the time the same way, 
but to return it to the Pascal program. I don't have the MPW 
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Rotated TextEdit 
White line fever? Anine-lane highway? 


Nope, selected text to measure the time 
to rotate a bitmap of mostly black pixels. 


'soxtd ayrymATysou jo dwugrq w 
9) 9101 0} JUTI IYJ IMS Bau OF NV} утра 
Ndu Артәут уто 520145 M 


мрзінәі равон 
Figuze 1. 


Pascal compiler, so I had to keep the timing at the assembler level. 
It's a drag being constantly forced into the debugger, so when 
actually using this program, I'd often patch Ше Debugger trap 
to a NOP, and then set a breakpoint there when I was ready to do 
the timing. 

The tick count is accurate to only 1/60th of a second, and the 
difference between two successive measurements is twice as 
inaccurate. Toavoid partof this, youcan synchronize the starting 
measurement with the beginning of one tick: 


поуе.1 ticks, 90 ; get the time 
61 cmp.1 ticks, dð ; changed yet? 


beq.s | 61 ; nope: loop. 
When you actually run the program, adding this code makes 
measurements noticeably more consistent. 


The Envelope Please... 

When you run the program with the above changes, how fast 
is it? Well, it depends on what kind of image you're copying: 
white pixels copy almost twice as fast as black ones. This is 
because the code sets the target bitmap to all white and then 
copies any black pixels in the source bitmap. 

As an initial benchmark, the four-way rotation program 
takes 12 or 22 ticks, for white and black pixels, respectively. The 
white-pixel benchmark is when the edit text is cleared com- 
pletely. The black-pixel case is when the edit text is all “—"s, 
selected to highlight it. (See figure 1.) 

So, from 12 and 22 ticks, how much can we improve? 


Start т The Middle! 
The central loop is where you should always start looking. 
It starts out by testing a bit in the word from the source bitmap: 
btst d6, d3 
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b NoBitToChange 
Since Dó runs from 15 down to 0 during the loop, it checks 


eachof the bits, going left-to-right. Instead of an explicit bit test, 
we can shift these bits off, one at a time. The fast way to shift a 
register left by a bit is to add it to itself. So discarding a bit and 


testing the carry can be done иш 
add.w 43, 93 test next bit. 
bcc.s МВ ToChange ' р "branch if not set 


Is this all that important? Well, not really by itself. (But it 
will help us get rid of D6 a little later on.) The speed with this 
change goes from (12, 22) to (12, 20). I think the ADD.W isn't 
actually faster, but the short branch is faster than the long branch 
for the black-pixel case. 


That's The Carry; Now The Cache 
Another rule of thumb is to keep variables in registers. Let's 
look a little farther ahead in the same central loop: 


поуеа.1 currentWord-localVars(a0), a2 
This loads a value which doesn' tactually change during the 


loop. In fact, we can get rid of the "currentWord" variable 
entirely, and just use A2 in its place. Then we can delete the line 
above, since the value is “cached”, and alter all three references 
to “currentWord-localVars(a0)” to just use “A2”. Note that one 
of the lines becomes: 

346.1 d7, a2 

It doesn't matter if this is a long or word subtract — they're 
the same for an address register operation. 

This speeds up the benchmark surprisingly, to (8, 12) ticks. 
Even the white-pixel case improves, because A2 is subtracted 
from in both cases. These two simple changes have given us a 
speed improvement of between 33% and 45%! 

Actually, the second timing for this version sometimes pops 
up as 13, not 12 ticks. This is nice, because even the slighest 
improvement will now change it to 12. For instance... 


Get The Address Right 
Addressing modes are important, too. For instance, just 
before the inner loop, the code picks up the next source word 
with: 
move.w (al), 93 
and after the loop, it advances to the next word with: 
eddq.] #2, al 
Instead of this, you can delete the second line and change the 
first line to: 


move.w (al)+, 93 
This little improvement is barely measurable. It just stabi- 


lizes the second measurement at 12 ticks. 


Overbyte or Underbyte? 
Now, one of the remaining big pieces of the inner loop is: 
n (а22,05 


94,85 
move.w dd, (а2) 
The idea here is that A2 points to a word in memory. But 


BSET acting on memory operates only on a byte. The existing 
code has to load a register so it can index up to 16 bits in the word. 

When D4 is between 15 and 8, a bit in the top byte of the word 
is set. When D4 is between 7 and 0, a bit in the low byte is set. 
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So if you knew that D4 acted on the high byte, you could use: 


bset 94, (a2) ; set it in high byte 
And if you knew it acted on the low byte, you could use: 


bset (4, 1(а2) ; set it in low byte 
Note that the bit number is taken modulo eight, so D4 needs 
no adjustment for the former case (no need to subtract eight). 
But it’s too expensive to make a check in the middle of the 
loop. Luckily, D4 stays the same over a stretch larger than the 
loop. So we can just adjust A2 to point to the right byte. Before 
the “rowloop” label, the new code is: 


cmp.w 87, 94 ; doing high byte or low? 
bgt dobyte1 ^ ; Skip if high byte 
вада 81, а2 ; else point to low byte 


dobyte 1 
And afier the end of the loop, after “пе rowloop”, this is 


compensated for with: 


cmp.w 87, 94 ; did we do by or low? 
bot dobyte2 / ” skip if high byte 
Subq 81, 82 ; else undo fudge to a2 


dobyte2 
The reward for all this effort is that those three instructions 
to load, alter, and store a word become this simple one: 
bset 04, (82) ; set bit in high or low 


This doesn’t help the white-pixel case, since the code above 
is used only to copy a black pixel. But the copy case speeds up 
from 12 ticks to 10. 

Note that using OR. W to set the bit would have been slower 
than the bit-setting method. Now, for the final optimization: 


Roll Over, John Olsen 
D6 isn’t used as anything except a counter in the inner loop, 
which now looks like: 


add.w 93, 93 ; test 2 in source 
bcc.s NoBitToChange ; not set? skip 
bset d4, (а2) ; set in high/low 
noBitToChange 

$46.1 d7, a2 ; Subtract rowBytes 


dbra d6,innerLoop ; loop 'til 46 = -1 
This is 5 instructions, one of which is devoted solely to 
counting a constant sixteen iterations. This is easy to fix: just 
repeat the first 4 instructions in-line sixteen times, and forget 
about counting at runtime. Except for the 16 labels to type in, a 
quick copy-and-paste session does this neatly. Plus you can ditch 
the code which initializes D6: 


тоуед.1 80 06 ; clear 96 
move.w 815,046; init inside loop counter 


This technique, "unrolling the loop”, is a big win! Both 
timings drop by 3 ticks for a final result of (5, 7) — down from 
anoriginal benchmark of (12,22). Asa wag on Usenet remarked 
the other day "Never put off 'til runtime what you can do at 
compile-time." 

The code printed along with this is the second half of the 
original ROTATE.A, with the above changes (there were no 
changes in the first half, which isn't time-critical). 


A Hack Too Far 


There's probably more that could be done here. For ex- 
ample, instead of advancing the local variable *wordCount" up 
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toa limit, decrementing it down to zero is faster to test. You can 
always squeeze another percent out of any piece of code — but 
is it worth it? The routine published here is “optimum”, in my 
opinion; it's been improved significantly without making the 
code unrecognizable or too unreadable. If this routine were 
actually used in a product, you might want to add (or even 
remove) some of these optimizations, depending on how impor- 
tant speed was. 


Summary 
With a couple of evenings of work, the bitmap-rotation 

routine's performance has been improved by a factor of about 2.5 
to 3. Standard rules of thumb were what helped the most: 

е instrument precisely 

* concentrate on the inner loop 

е make efficient use of registers 

* exploit addressing modes for the instruction set 

° unroll important loops 


Almost any significant piece of code, in any language, can 
benefit by a review by someone other than the author. The 
original author “knows” too well what the code is supposed to do. 
One approach for a programmer trying to optimize is to look at 
the code without comments, just look at what's happening to the 
data. Being forced to reverse-engineer a subroutine can help 
inspire “peephole” optimizations. The Zen of Low-level Optimi- 
zation consists of looking at what the code does, not what it was 
intended to do. 


Listing: rotate.a 


INCLUDE ‘SysEqu.a’ ;the usual system equates & macros 
INCLUDE 


INCLUDE 


‘Тгарз.а’ 
'QuickEqu.a' 


newPtrClear FUNC EXPORT 
IMPORT SAVERETA 1 
MOVE.L CSP2*,A1 
MOVE.L СР )+,00 
-NewPtr clear 
MOVE.L Аб, CSP) 
JMP SAVERETA 1 


ENDF 
Rotate PROC EXPORT 


PROCEDURERotate CsourceMap, destMap : bitMap ); 


given а source and destination bitmap rotate it CCW 90°. 
bitmap can be of any size, we will align on word boundaries 
(v & h) 


ай = result of —newPtr call 00 = size of bitMap allocate 


wo We We Ҹо We We We We We We % е `. Ҹо We BD 


| 
al = ріг to src bitMap | dis width/2 (source) 
a2 = ptr to dest bitMap | d2 = height/2 (source) 
a3 = dest bits | d3 = left | top 
84 = copy of dest bits | 94 = ctrPt.h 
a5 = not used | 45 = ctrPt.v 
a6 = not used | 46 = right | bottom 
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; 87 = not used | d7 = rowBytes of dest bitMap 


2 


; 
ХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХ ХХХ ХХ 
x x 


; 
ЕЖ Initialize destination bitMap CdestMap), etc.. 

; x 

д 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖ 
; peremeter offsets 


7 

DestMap EQU 4*4 ; offset to dest bitmap ^ 
SourceMap EQU DestMap + 4 ; offset to source bitmap ^ 
create local stack freme, and save some registers 
make room for dest rect to be passed back 


we ` 


`. 


link а6,80 ; Set up а stack frame (no butes) 
поуеп.1 d3-d7/a2-a5,-(sp) ; save registers pascal may need 


поуе.1 SourceMap(a6),a1 ; point to the source BitMap 
поуе.1 DestMap(a6),a2 ; point to the dest BitMap 


compute height of source BitMap rounded up to nearest word 


we 


move .м boundstbottom(al),d7; get bottom and put in d7 
sub.w bounds+top(al),d7 ; bottom - top = height, put in (7 
move .w 97, 90 ; save a copy of height for later 
; rnd = Cheight+15)/16, follows: 

addi.w 815,07 ; add 15 to the height, put in d7 


Isr 84 97 ; divide by 16 
1681 81,97 ; multiply by 2 = rowBytes of dest 
bitMap 


d7 now contains rowBytes of dest bitMap 
now compute the destRect for dest bitMap 


compute center point of Source rect 

note the center points ere not necess. the 

same in the vert dir. relative to srcMap 

beceuse of rounding that follows Ci.e. height 

of srcMep is dir. prop. to RowBytes of destMap) 

Isr 81,00 ; divide height by 2 

move.w 90,92 ; make а copy of height/2 for later 
move.w bounds+top(al),d5 ; get ‘top’ of source rect 

add.w 90,95 ; 95 contains vert compnt of ctr pt 
; compute the width of src rect & put in d4 

move.w boundstright(€al),d3 ; get right and put in аз 

Sub.w bounds+left(a1),d3 ; right - left = width, put in d3 


we We We We We We We We BW 


Isr 81,93 ; divide width by 2 

move.w 93,91 ; маке а copy of width/2 for 
leter 

move.w boundstright(al),d4 ; get right of source rect 

sub.w d3,d4 ; 94 contains horiz compnt ctr pt 


now get center point апа compute bounds for dest bitMap 
height and width аге reversed now for the 2 bitMaps 

left :=ctrPt.h - height /2 

top :SctrPt.v - width/2 

right :=ctrPt.h + height/2 

bottom:=ctrPt.v + width/2 

SetRect(rect, left, top, right, bottom) put data direct to 
avoid the overhead of а trap call 


we We -. We We We We We We We We 


compute ‘top’ 
move .w (45,03 
sub.w 41,03 
swap d3 


get а copy of ctrPt.v апа put in 93 
ctrPt.v - width/2 = 'top^ in d3 
move 'top^ to hiword 
compute ‘left’ 
move.wd4,d3; get a copy of ctrPt.h and put in loword d3 
sub.w d2,d3 ; ctrPt.h - height/2 = ‘left’ in 
loword d3 


we Be We “% = 


“ we now have ‘top’ in hiword k ‘left’ in loword d3 
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compute ‘bottom’ 

get а copy of ctrPt.v in of 93 
ctrPt.v + width/2 = ‘bottom’ in 93 
move 'bottom^ to hiword 

; compute ‘right’ 

move.w d4,d6; get а copy of ctrPt.h and put in loword d6 
add.w d2,d6; ctrPt.h + height/2 = 'right^ in loword 96 


move.w d5,d6 
add.w di,d6 
swap (46 


“. We We We 


we now have ‘bottom’ in hiword & ‘right’ in loword d6 


assign data to dest bitMap structure directly 


we We We We Ve 


move.w d7,rowBytes(a2) ; put in rowBytes for dest bitMap 
поуе.1 d3,bounds*topLeft(a2) ; put the coord pair in direct 
move.] 40, boundstbotRight(a2) ; put the coord pair in direct 
move.w 97, 90 ; put rowbytes іп 00 
mulu rowBytes(a1),dð ; multiply rowBytes src*dest = d 
161 83,00; multiply 90 by 8 for size of dest bitMap 
-NewPtr clear; allocate size of dest bitMap (a2 pts to it) 
поуе.1 af,baseaddr(a2) ; move ай to baseAddr field 

; of dest bitMap structure 


‚ аб = baseAddr for our locals | dø = rowbytes of srcMap 
al = points to bits of src bitMap| d1 = width/2 (source) 
а2 = ptr to dest bitMap | 92 = height/2 (source) 
83 - dest bits | d3 = current word srcMap 
84 = | d4 = сору of width of srcMap 
a5 = not used | 95 = current destMap word 
аб = not used | 46 = insideLoop count (current bit) 
a7 = not used | d7 - rowBytes of dest bitMap 


P 
4 
4 
7 
7 
7 
2 
д 
д 
f ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖ 
; x 

ES Start actual rotation of bitMaps 

‚ Ж 

; ХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
; Assumptions: 

4 
ГА 
7 
7 
7 
д 


‚ height of destination bitMap = rowBytes of srcMap 


; Get the baseAddr for our locals into ай - this will make our 
; program much more readable as we will let the assembler do 

; 811 the addr location calcs for us. The addresses will be а 
; fixed number while the programs is (locked down) and 
running, 

; therefore, there is no runtime penalty for doing this addr 
;calculation 


lea localVars, ай 


; Synchronize with the TickCount rollover. 

move.l ticks, d ; get the time 
бістр.1 ticks, dð ; changed yet? 

beq.s 61 ; hope: loop 


; Strobe the starting time. 
поуе.1 ticks, startTime-localVars(ad) 
save Starting time, in ticks 


initialize dð to contain the pointer to the srcMap 


<. w. We Ve 


move.wrowbytes(al),d@ ; get rowbytes of srcMap 
; get regs pointing to bits 


move.) (а10,81 ; al pts to BITS of src bitMap 


move.] (а2),а3 ; а3 pts to BITS of dest bitMap 
compute the lower left corner of the destMap - this maps to 

the upper left corner of the srcMap and will be used as base 
from which to offset intothe dest map when we need to set a 

bit 


we We We `. We 
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сіг.1 41 
move.w 90,91 


; cleer 41 

; load rowBytes of srcMap 

; CrowBytes of srcMap = ht of destMap) 
1$1.и 83,01; multiply by 8 to get ht of destMap when rot d 
mulu.w 47, di; multiply by rowbytesCdestMap) = "words in 

Sub .w dT, di ; destMap less one row 

аса.1 a3,d1 

add the computed offset to the baseAddr of destMap 

поуе.1 d1,lowerLeft-localVarsCaQ) ; init lowerLeft 


“. 


7 

; 80 = baseAddr for our locals | 00 = rowbytes of srcMap 

; 81 = points to bits of src bitMap| di = SCRATCH 

; 82 - SCRATCH | d2 - colmCounter 

; 83 - dest bits | d3 - current srcMap word 

; 84 - SCRATCH | 94 = colmBitLoop counter 

; 85 = not used | 95 = current word destMap 

; аб = not used | 96 = insideLoop count (current bit) 

; а! = not used | d7 - rowBytes of dest bitMap 
-Debugger ; 


; init wordCount to zero 


move.w 80 wordCount-localVarsCa2) ; 
before we start 
j 
; init colmLoop counter 


) 


set wordCount to one 


move.w d7,d2 
Isr 81/42 
; divide by 2 - 92 now contains the outer counter 
move.w d2,colmCount-localVars(ad) 
; put the max value анау for reference 
поуед.1 #89, 92 
; Set 42 to zero since we use it Гог the counter 
со1пгоор 


; get rowBytesCdest) 


; : this is the outside loop 


” move.w #15, 04 ; init colmBitLoop counter to 15 
поуе.1 lowerLeft-localVars(a0), a2 ; init currentWord 


colmBi tLoop 

; this is the loop that does the bit counting in the des tMap = 
; it is really a misuse of the ‘dbra’ instruction since it is 
; hot an independent loop but itis a quite cheap method of 

; doing our counting 


cmp.w 87, 44 , ёге we doing high byte ог low? 
bgt dobyte 1 ; Skip if high byte 
eddq #1, а2 ; else point to low byte 

dobyte 1 

rowLoop 


; loop across each row in the srcMap and keep count each time 
; ме do а row this ‘rowCount’ will used to compute the offset 
; from ‘lowerLeft’ 
move.w (а1)+, 93 ; get а word to rotate into 93 
addq.w *2,wordCount-localVarsCa?) ; add 1 for each word 
ооо jdoooo 


add.w d3, d3; test next bit in the current source word 
bcc.s NoBitToChange ; if bit’s not set, skip to next 
bset 44, (a2) 
; set proper bit in high ог low byte in currentWord 
noBitToChange 
sub.] 97, &2 
; subtract rowBytes(destMap) from current word 


; Do the same as above, fifteen more times. 


edd.w d3, d3 
bcc.s 81 
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bset 
e1sub.1 


add.w 
bcc.s 
bset 
@2sub. 1 


add.w 

bcc.s 

bset 
e3sub.1 


edd.w 
bcc.s 
bset 
@4sub. 1 


add.w 

bcc.s 

bset 
e5sub.1 


add.w 
бсс.5 
bset 
@6sub. 1 


add.w 
bcc.s 
bset 
@7sub. 1 


edd.w 

bcc.s 

bset 
6e8sub.1 


add.w 

bcc.s 

bset 
e9sub.1 


edd .w 
bcc.s 
bset 


d4, (82) 


d3, d3 
44, (a2) 


610 346.1 d7, a2 


add.w 
bcc.s 
bset 


d3, d3 
e11 
d4, (а2) 


611 sub.1 97, a2 


add.w 
bcc.s 
bset 


d3, 93 
012 
44, (а2) 


012 sub.| d7, a2 


add.w 
bcc.s 
bset 


d3, d3 
e13 
d4, (a2) 


613 346.1 d7, а2 


add.w 
bcc.s 
bset 


d3, d3 
614 
d4, (a2) 


614 ѕир.1 d7, a2 


edd.w 
bcc.s 
bset 


d3, d3 
615 
44, (82) 


615 56.1 97, a2 


* at this point we've just completed a word from the ѕгсМар 
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д 


стр wordCount-localVarsCa),d0 
; стр wordCount to rowBytes-are we done with а row ? 
bne rowLoop ; no - do another word 
cmp.w 87, 04 ; did we do high byte or low? 
bgt dobyte2 ; Skip if high byte 
subq #1, а2 ; else undo the fudge to 82 
dobyte2 


2 


we We We We We We 


we We 


wee We 
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; we just completed а row so add 2 to the count 


move.w *g,wordCount-localVarsCe?) 
000jdo000 reset wordCount to zero 


the following use of dbra keeps track of destMap bit for us 
тоуе.1 lowerLeft-localVarsCa0), a2 ; re-init currentWord 


; set the currentWord to the lowerLef tCcurrent) 
; lowerLeft is moved over (right) by a word each 
; tine we do 8 row in the srcMep 
дога  d4,colmBitLoop ; go thru the bits (159) in the 
; destMep - then exit and do it 
; again for rowBytes/2 times 


were done counting thru the bits of а destMap word - at this 
point we have actually finished а column in the destMap. The 
column is а multiple of 16 bits wide (and being at least 1 
colm) and as tall аз the destMap is (which is also equal to 
rowBytes of the srcMap) 

addq.1 #2, lowerLef t- locelVersCa?) 

this moves us into the next 

‘column’ of bits in the destMap 


addg.w 81,42 ; add 1 to the colmLoop counter 
cmp colmCount-localVars(a8),d2 ; are we done yet ? 
bne colmLoop ; no - do it again 


; else we're done 


were done so lets do our clean-up/restore and go away 
grecefully 


move.] ticks, dð ; get the current time.. 

sub.] stertTime-localVarsCa0), dð ; .less starting time 
-Debugger ; and let me see the time it took 
movem.1 (sp)+,d3-d7/a2-a5 ; restore registers 

unlk аб ; Clean up stack frame 

move.] (sp)+, аб ; return address 

249.1 88 әр ; рор parameters off stack 

jmp (а0) ; bye y'all! 


; set up our data storage area 


localVars ; the beginning of our local var storage area 
colmCount ds.w 
currentWord  ds.1 


wordCount ds.w 


1 
lowerLef t 08.1 1 
| 
| 


startTime ds.1 


ENDP 
END 


Listing: Build Script 

иий Assemble, link, and rez the rot4edit program, 
#88 including the changes in rotate.a. 

asm rotate.a -o rotate.a.o -wb 

link -о testProg rotate.a.o rot4edit.p.o 
(mpw)libraries:Runtime.o (три) libraries: Interface.o 


(mpw)Plibraries:paslib.o 


rez -а -о testProg rot4edit.r м 
testProg (СТА 
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Assembly Lab 
Smoothing via PicComments 


Inside PicComments 

Everything you' ve always wanted to know about picCom- 

ments but were afraid to ask. 

Raul Tabasso is currently working on his thesis in Architec- 
ture at the University of Rome where he was particularly in- 
volved in designing a CAD system. At the end of 1984 he started 
developing software on the Mac and since then it has become his 
principle activity. At the moment he is working ona large project, 
а Macintosh application written in assembly language that will 
eventually allow bitmaps (like those digitized with scanners) to 
be transformed into a collection of objects as in a PICT file. In his 
younger days Raul worked for a week as a bicycle messenger in 
San Francisco where he learned how to overcome slopes. 

When I first read the Laser Manual and Apple Technical 
Notes on the subject, I was very surprised to see how easy it 
seemed to implement some laser specific features without the 
bother of sending a special PostScript (PS) program to the printer. 
Actually the idea of passing information to the laser driver 
through picture comments not only makes it very easy to include 
some features in your programs, but guarantees longevity and 
stability to your code utilizing the power of PS through Quick- 
Draw (QD). In fact even if one day this technique could be 
replaced, Apple will hardly change the rules its own applications 
and many others depend on. This is at least if you don't take 
picComments (from now on picComs) just like a trick to send 
your own PS programs which, although it now works, could 
really break the rules of device independence. 

If youhave experienced picComs you probably realized that, 
despite revisions, Apple's own documentation surprisingly lacks 
precision and cleamess in more than one point and that such а 
brilliant idea appears not to have been supported as it should. 
Since a lot has been already written about picComs ап not going 
to repeat basic information most of us already read but I will 
concentrate on the more obscure and less sampled aspects. For 
example one of the most exciting features of picComs is the 
ability to have easy access to PS equipped printer’s capability to 
smooth polygons using bezier curves. As far as I know (you can 
check how far in the bibliography), nothing has ever been shown 
about printing smoothed polygons using this scheme. Further- 
more we will examine the inner working of one more 
*unrevealed' picCom, the SetLineWidth. 

* Please note that through this article we will use the term 
laser or laser driver for convenience where we shall actually be 
referring to any device and driver that can process picComs. 
Seemingly the term imagewriter will be referred to those devices 
and drivers ignoring picComs. Moreover, since there is no reason 
your application can't make sure it is running on a recent driver, 
I cannot guarantee everything will work as described in this 
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Figure 1. Sample Smoothed Picutres 
article using earlier versions of the 4.0 laser driver ° 


A Different Approach 
Before we get involved with smoothing, there is something 
to point out on sending picComs to the printing grafPort that I 
think is fundamental and seems to have been left out of any 
discussion. You probably noticed that all the examples published 
are structured something like this: 


myPic := OpenPicture(theWorld); 
DrawStuff ; (with QD + picComments) 
ClosePicture; 


PrintThePicture; (go print пуР1с} 

This will work nicely in an example test or in a small 
program, but in a real application will probably give you some 
problem. Why? Very simple. Since you usually give the freedom 
to your users to draw as many polygons or rotated texts as would 
fit in the available heap, it can easily happen that there isn’t 
enough memory to make a picture containing all graphics to be 
printed or saved. 

So what to do? Can we divide the picture into smaller ones? 
If so we must create and kill pictures in the middle of the printing 
loop, and this is not allowed as specified in IM2 (p. 160) where 
they warn us: “Don’t call the QuickDraw function OpenPicture 
[...] after a call to prOpenPage ...” . Do we have to open a picture 
in order to use picComs? Although we usually must, when 
printing we do not really have to. 

Let’s have a look at some facts now and see why this is 
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possible. When we аге spool printing on an imagewriter, the 
driver is actually writing a PICT format file on the disk (or 
possibly to memory). To accomplish this, it has to solve the same 
problem we just talked about, as nothing guarantees that it will 
have enough memory to accumulate the picture and eventually 
print it. Fortunately, it is possible to customize the standard 
QDprocs, the low-level bottleneck drawing routines of QD. The 
imagewriter driver customizes the stdPutPic procedure (in the 
PrOpenDoc call) in order to directly write the picture to disk 
while it is forming, instead of accumulating it in memory, and 
opens a picture in the PrOpenPage call. Since another picture is 
already opened you can't open one after, but just because of that 
we can issue our picComs without taking the trouble (and the 
memory) of making one by ourselves. The standard com- 
mentProc for the print port of the imagewriter will just ignore 
comments anyway. 

Iknow you are wondering what if we are printing on a laser, 
since it usually prints in a draft mode. Ok, we don't have a picture 
opened and we are not writing a PICT to the disk, but the driver 
has customized the commentProc that, as you guessed, is in 
charge of processing picComs causing them to be directly inter- 
cepted and sent to the laser without being accumulated any where. 

All this simply means that you can safely issue picComs in 
your page loop without having to pass through the construction 
of a picture, this allowing you to print everything you want 
without worrying about memory problems besides making your 
print job faster and easier. 

So our previous routine should look something like this: 


PrOpenPage(MyPr intPort, NIL); 
ture) 

DrewStuff; (using QD + PicComments) 
PrClosePage(MyPrintPort); (end cur page) 


(don^t need to open а pic- 


Smooth Commenting 

When we have to smooth polygons we usually write a 
routine that draws many short line segments shaping the curve. 
We can use it to draw on the screen or in the printing grafPort of 
the imagewriter, but no matter how good our smoothing algo- 
rithm is, when we attempt to send it to a laser printer the results 
are far from being attractive. This is because the smooth-poly will 
always be printed at a 72 dpi resolution, making your hard copy 
much less impressive than it could be. This, of course, is before 
using picComs for your poly (sorry if it sounds like an ad). 

Using picComs is not only useful for printing but very 
recommendable for saving (in a file or in the scrap) a PICT 
containing objects that can be better explained adding comments. 
Doing it in this way will allow other applications to reconstruct 
the objects in the right format. To simplify this, imagine that you 
have just saved in a picture file the short line segments forming 
the smooth-poly. Ап application like Mac Draw does not know 
that you do not want a very fractal object or just a number of 
connected lines, thus treating your masterpiece like a senseless 
doodle. Using picComs you can tell MacDraw that those short 
lines belong to a smoothed polygon. 

Although the whole mechanism is pretty easy (once you 
know it) there are some rules to follow. The final goal of our 
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discussion is to write a routine that is not concerned with the 
printer type but that takes advantage of specific situations with- 
out risk of being device dependent. This routine could also be 
called in order to save (on disk) or to copy a picture (in the scrap). 
In fact it is indifferent to send our picComs and drawings to the 
printer, to the disk or to the memory. 

It is important to notice that some applications, like 
MacDraw (and our demo), do not always use a standard QD 
polygon (a 10 bytes header plus 4 bytes for each point), but a 
compressed version. When several polygons with many sides are 
in memory, the use of compressed polys could save a lot of 
memory. If, for example, you use a byte offset format nearly half 
the space can be saved. It is not convenient then to convert this 
object to a standard Poly in order to draw it using stdPoly; in fact 
it will be more trouble and take more code and memory than if 
you simply drew it using stdLines. Subsequent calls to Lineto or 
Line, after the PolyBegin comment, will be interpreted as part of 
the poly. 

Let's now have а closer look at this routine. We always start 
the poly definition with a PolyBegin comment. This informs a 
driver, prepared to understand picComs, that the following 
stdLines (or stdPoly) are to be considered as part of a special 
polygon. Immediately following this comment we might issue 
the PicPlyClo comment which specifies that the polygon is a 
closed figure. 

This header is the same for smoothed or unsmoothed polys, 
but at this point we should differentiate our code. If the current 
poly is not to be smoothed we can just draw it normally which 
would work for every printer; but if it does have to be smoothed 
we should issue additional information which is done through 
another picCom, the polySmooth. 'This comment takes a handle 
to one byte of data specifying the nature of the splined poly: the 
verbs parameters. These verbs provide a way to apply framing, 
filling and closing to the current object. 

Right after this last comment we should draw the un- 
smoothed poly. Notice that we draw the original poly even 
though we want the smoothed one, since the laser only cares 
about the original vertexes on which will be applied its own 
smoothing algorithm (a cubic spline, if you care). If you are 
wondering, what if an imagewriter gets these vertexes instead of 
the smoothed ones, you have probably guessed that it would print 
the wrong thing, so we have to find a way not to have it print on 
paper. The official Apple documentation suggests setting the pen 
size to zero after the polyBegin comment. Unfortunately this 
method doesn't work properly. It does avoid printing the un- 
smoothed poly ona printer that is not equipped to handle polygon 
comments but, too bad, even on the laser the pen remains at zero 
and nothing will print. 

The real solution has to do with clipping. What we have to 
do is simply set the clipping to a zero rect (a rectangle enclosing 
no pixels) before drawing the unsmoothed poly and then reset it 
to the previous clipping when finished. This will prevent an 
imagewriter from drawing the wrong thing, but will allow a laser, 
that ignores the clipping rectangle (when in a special poly 
definition), to draw the smoothed polygon. 

e It is interesting to note that a picture with the clipRgn set to 


© The Definitive MacTutor, Vol. 4 


ап empty rect does not generate any opcode for this operation 
since such a clipping is actually its default * 

At this point we are done with the laser, but nothing would 
have been printed yet on an imagewriter, so we must get ready to 
call our own smoothing algorithm. However, first we must 
ensure that the laser won't draw again. This is very easily done 
by the polyl gnore comment that simply puts the laser driver to 
sleep (actually only drowsing) until a polyEnd is encountered. Is 
that all? Basically this is it, but there are a few other things we 
should examine to completely master the whole scheme. 

If the polygon has to be filled, as well as using the ДИ verb 
in the PolySmooth comment, the QD procedure fillRgn сап be 
used. This comes after the PolyI gnore and will work for every 
printer. In fact the laser driver, even though it ignores regions, 
will be awakened from its sleep and will build а Ра for its 
current path using that passed to the FillRgn proc. Some of the 
patterns have been optimized in order to translate them in a gray- 
scale that PS can halftone. The actual patterns that the driver 
transforms in a gray-scale, are the standard fill tones present in 
the system file (and as QD globals) plus some of the patterns in 
the standard list of the system file: to beexact those with numbers 
1 to 5 (225) and 20 to 24 (23224). АП these patterns can be found 
as resources (PAT# ,IDz-8191) in the laser driver where, two 
more pats in the list (8 and 18), raise the total available shades of 
gray to the number of 11 including black and white. You can, 
therefore, easily put up a pattern menu with more real PS gray 
scales than most applications without having to deal with special 
coding or, in the worst case, having to write a driver yourself. In 
addition these patterns are much faster than others because they 
don't need to be imaged before being sent to the laser. Using these 
pats you can have gray-scales from white to black at approxi- 
mately 1046 increments in gray percentage. Currently there is a 
gap between 50 and 75 percent and there are 3 gray levels 
between 75% and 82% all very similar, so let me put on the wish 
list a gray around 60% instead of one of these last 3. 

Let's summarize all this with a short pseudo-language 
example assuming our polygon is stored in a byte offset format, 
therefore using Line or LineTo procedures in its drawing rou- 
tines. Shouldn't be hard to adapt this example in order to use 
normal QD polys. 


PrOpenPageCMyPr intPort ,NIL2; 
(Begin special poly) 
PicComment(PolyBegin,9,NIL); 

PicComment(picPlyClo,8,NIL); 

IF smoothed THEN BEGIN  (smoothPoly) 
(verb is an unsigned byte) 
IF noFill THEN SmoothHd1^^ .verbz5; 
(close*frame*fill (4+1+2)} 
ELSE SmoothHd1**.verb=7; 
(set smooth flag апа verb) 
PicComment(Polysmooth, 1,SmoothHd1); 
GetClipCsaveClip); 
(laser don’t care of Clip) 
ClipRect(ZeroRect); (but others do) 
(feed laser with original vertexes} 
DrawUnsmoothedPoly; 
SetClip(saveClip); (restore) 
(laser can take а nap now) 
PicComnentCPolyIgnore,9,NIL); 

END; (smoothPoly) 
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(check err) 


IF filled THEN BEGIN 
(make а гоп to fill our special poly) 


OpenRgn; (assuming we have а 
handle) 
DrewCurPoly; (create re- 
gion) 
CloseRgnCRgnHandle?; 
FillRgnCRgnHandle, itsPat); 
END; 
DrawCurPoly; {redraw} 


PicComment(PolyEnd,@,NIL); 

(End special poly} 
PrClosePage(MyPrintPort); (end cur page) 
PROCEDURE DrawCurPoly; 

{decide what routine to call} 
DrawSmoothedPoly; 

ELSE DrawUnsmoothedPoly; 


END; 


IF smoothed THEN 


Les jeux sont fait; this routine will print on any kind of 
printer regardless of whether it knows how to interpret picComs 
or if the current poly is smoothed or unsmoothed. The scheme 
represented in this routine is similar to that used by MacDraw and 
this guarantees that it will be supported for a long time. 

As we said, besides to print, we can use this routine to store 
in the scrap or to save a PICT file on the disk and we can even use 
it to draw on the screen (although it’s slower than normally). 
When we wantto save a picture in the scrap we open a picture and 
then call our routine causing drawings and picComs to be 
accumulated. In order to inform an application receiving our 
PICT that it contains comments, we should bracket the special 
poly in two additional comments: picDwgBegin and 
picDwgEnd. Although these comments were designed for 
MacDraw, some other application could count on them, so even 
if they might be useless we should include them. 

Let's now see a slightly different way to accomplish the 
same task which is derived from the new scheme used in 
MacDraw II. Basically it doesn't differ much from its predeces- 
sor except for the method used to fill the poly. As we recall from 
the previous example a region was build to fill the pseudo-poly 
whether it was smoothed or not, but, as we'll see now, a standard 
QD polygon can be used for the same purpose. 

Using a QD poly, of course, involves building one. Keeping 
track of its size is a much more easier thing to do than for regions. 
In factif you inconsiderately trespass the 32K limit of regions and 
polygons some really undesirable things will happen soon. How 
too make sure this won't happen using a region is (too bad) 
beyond the scope of this article but, as you probably guessed, 
checking for this kind of error while a polygon is forming is a 
much easier task: just make sure you don't have more then 8189 
points or, using GetHandleSize, check for the 32K limit not to be 
passed. The original MacDraw ignores afill request for a polygon 
that does not fit in a 32K region. This means that if you try to fill 
a big and complicated smoothed poly MacDraw refuses to do it. 
Surprisingly MacDraw II doesn't take advantage of a much 
easier size checking derived by using polygons and dies in a 
horrible way when overloaded. 

Here is how it could look like our previous routine modified 
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| 
in order to use the procedure FillPoly instead of FillR gn: 


PrOpenPage(MyPr intPort,NIL); (check err) 
PicComment(PolyBegin,@,NIL); 
IF Fill THEN BEGIN (build Poly) 

ThePoly := OpenPoly; 

DrawCurPoly; (accumulate lines) 

ClosePoly; 

END; {build Poly} 

IF smoothed THEN BEGIN  (smoothPoly) 
IF noFill THEN SmoothHd1**.verb=5; 
ELSE SmoothHd1^*^ .verbz7; 
PicComment(Polysmooth, 1, SmoothHd1); 

END; (smoothPoly) 

IF Fill THEN FillPolyCThePoly, ThePat); 

GetClipCsaveClip); 

ClipRect(ZeroRect); (laser ignores this) 

DrawUnsmoothedPoly; {original vertex) 

SetClipCsaveClip); (restore) 

PicCommentCPolyIgnore,9,NIL); 

DrawCurPoly; (draw poly frame) 

PicCommentCPolyEnd, 2, NIL); 


PrClosePage(MyPrintPort); (end cur page) 


Notice that, as shown in the other example, the procedure 
DrawCurPoly checks whether the poly is smoothed and, if this is 
so, calls the smoothing algorithm, otherwise draws the lines 
shaping the poly using original vertexes. When wecall DrawCur- 
Poly right after the PolyIgnore picCom it might also be possible 
to issue a FramePoly QD proc instead. In this case nothing 
guarantees you were able to build one since it might have 
happened that the poly exceeded the size limit making its creation 
impossible. Using stdLines always guarantees you will be able to 
frame your object. 

MacDraw II actually does a few other things than in this 
example. Those things seem completely useless to me, so I took 
them out of the example test that demonstrated to work well even 
without those cryptic statements. In fact MacDraw II would start 
moving the pen out of the way (-8000,-8000) and then setting the 
pensize to zero, however, after the FillPoly proc (before any 
intervening drawing), it would reset the pensize and location 
cancelling the previous operation. Mac Draw II uses azero region 
to fill the poly (as we discussed before). The laser driver is not 
concerned with the region data but uses only the fill pattern 
passed along with the procedure. This, again, is useless since the 
driver would have already taken the pattern at the issue of the 
FillPoly proc in order to fill its current path. Note that MacDraw 
II passes a 2 bytes verb in the PolySmooth picCom instead of the 
only one used originally. However this second byte seems not to 
be used and cleared to zero at the moment. 

Although there might be some invisible reason (at least to 
me) for MacDraw II to use this additional statements, you can 
safely use the slimmed version we just saw or the scheme used by 
the original MacDraw shown before ( and also presented in the 
demo). Both of These methods have demonstrated to work 
fluently in all the tests I produced. They also worked fine in order 
to save a Pict file format on disk. In this case we must write a file 
having cleared to zero its first 512 bytes block (usually contain- 
ing MacDraw specific information) followed by our picture. As 
we said for the imagewriter driver, we may not have enough 
memory to accumulate the picture in memory before writing it to 
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disk, so we should customize the stdPutPic in order to directly 
spool it to disk while it is forming. 


Real Width 

Let's now have а look to another interesting picCom which 
has the ability to scale the pen size even under the smallest unit 
(1/72 of an inch) that QD can represent. We are talking about the 
SetLineWidth (from now on SLW) comment that allows you to 
draw with an almost infinitely thin pen, taking advantage of 
higher resolution laser printers. 

This is a very important comment that, I think, every 
application dealing with graphics should use in order to give its 
users the possibility to fully utilize laser capabilities. 

SLW takes a handle to a 4 bytes data point which is actually 
to be interpreted as a real number. The first high order integer (2 
bytes) is the numerator and the second the denominator of a 
fraction giving the scaling factor for the current pen. For example 
if you pass 1 for the numerator and 4 for the denominator you will 
have a value of 0.25 (1/4) that will be used to determine the 
current pen for the SetLineWidth PS operator. 

° Don'tconfuse the SetLineWidth picCom with the homony- 
mous PS operator which actually assigns the pensize for the laser 

The LaserPrep file contains variables and procedures that 
the driver downloads to the printer. The SLW рісСот works by 
changing the value of some of these variables. There is a global 
variable flag string (fg) containing single-character values; the 
fourth and the fifth parameters of this string represent respec- 
tively the numerator and the denominator of a variable named 
pnm. The SLW picCom stores the two parameters it receives in 
these character bytes therefore limiting to an unsigned byte (0- 
255) the maximum possible value that can be passed. Note that 
you pass numbers in integer format but they are interpreted as 
unsigned bytes. If for example you wish to scale your pen to 300 
dpi (instead of the 72 default), it would be fatal to issue a SLW 
having 72 in the first word and 300 in the second ($ 0048 012C). 
In fact, the number 300 will not fit in the unsigned byte denomi- 
nator of pnm which would cause the driver to print nothing or to 
bomb totally (depending on version). To perform such an opera- 
tion, scale the number to a common factor like 12 for example, 
giving a fraction of 6/25 which will scale the pen exactly like 72/ 
300 would have done. 

Unfortunately the SLW picCom is very tricky and often 
doesn'tappear to workas expected until you know its idiosyncra- 
sies. Let's see the inner workings of this comment in conjunction 
with the laser driver. 

* For simplicity we'll consider width and height of QD pen 
as a unique parameter ° 

Any time you issue a $LW picCom, in the printing loop, the 
laser driver translates it into a call to the previously downloaded 
Iw (line width) procedure. The [м proc calculates the width of the 
pen that is used for the SetLineWidth PS operator. If we name 
"LineWidth' the variable containing the thickness of lines to be 
drawn (what an imagination) and ‘pnmV’ and ‘pnmH’ are the 
two parameters you pass in (ће SLW picCom, the lw procedure | 
works about like this: LineWidth = LineWidth * (pnpmV/pnmH). 
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Then the SetLineWidth PostScript operator will take LineWidth 
asits argument setting the pen for the laser to this new value. This 
means that every new scaling factor you pass through the SLW 
comment will not actually act on the current QD pensize, but will 
multiply the PS pen. For example if you have a starting QD 
pensize of 2 and you pass a pnm of 3/2 (1.5) the PS pen will be 
set to 3 and this is no surprise, but if a further SLW is generated 
with a pnm of 1/2 (0.5) we will have a new pen of 1.5 (3 * 0.5) and 
not 1 as would have resulted multiplying the QD pen (2) with the 
new scaling (0.5). So one more SLW comment with a рпт=0.5 
will set the PS pen to 0.75 leaving unchanged the QD pen (2). 

Further more we must not forget that even the pensize QD 
procedure affects the laser pen width, but differs from the SLW 
picCom, in that it is not directly processed and sent to the laser. 
In factuntil a new drawing routine is called, arguments passed to 
pensize are only recorded but no action is taken. When a QD 
bottleneck is called the driver checks the last value passed to 
pensize and, if it's different from the previously used value, it 
generates a “реп” LaserPrep's routine. Imagining the new QD 
pensize to be a unique value (for width and height) named 
NewSize this procedure would look about like this: LineWidth = 
NewSize * (pnmV/pnmH). LineWidth will be then passed to the 
SetLineWidth PS operator. 

This procedure will have the effect of resetting the laser pen 
according to the new QD pen and the current pnm. So, consider- 
ing we leftour PS pen to 0.75 and the pnm to 0.5 as in the previous 
example, making a call to PenSize with an argument of 1 would 
cause the pen (when a QD proc is called) to be set at 0.5, indeed 
NewSize * pnm (1 * 0.5). 

Notice that, because the laserPrep's “реп” procedure is 
called right before a QD routine (if at all), it is always issued after 
the “ім” procedure even if the original order was the opposite. 

So many things just to set a pen width? Don't ask me, but 
once you figure out the mechanism it shouldn't be impossible to 
make it work. I suggest that, following the rules we have just 
talked about, you write a short routine in your favorite language 
to test all the quirks of this comment. 

Here'sa pseudo one that can serve as a skeleton and assumes 
(for simplicity) the QD pen to be a unique value: 


LineWidth = Float (PS pen) 
QDPenSize = Integer (QD cur pen size) 
pnm - Floet (pen multiplier) 
NewSize = Integer (last val of PenSize) 
(Everytime а SLW picCom is issued call the followin proc to 
simulate the driver) 
PROCEDURE Lw (pnmH,pnmV); 
pnm := pnmV / pnmH; 
LineWidth := LineWidth * pnm; 
END; (Lw) 
(If а QD PenSize is called just set NewSize accordingly) 
(Before drawing, check IF QDPenSize O NewSize THEN Cin case) 
call this routine) 
PROCEDURE Pen; 
QDPenSize := NewSize; 
LineWidth := QDPenSize * pnm; 
END; (Pen) 
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(You can then print LineWidth, instead 
drawing, to test the PS pen size } 


About the Demo 

The principle goal of our Demo is to show how to correctly 
insert in a working program the routines we have been talking 
about. 

The program allows a polygon to be drawn (in a non modal 
way) in a standard Macintosh window, you can then take some 
action on it through menus. It is possible to smooth and vice- 
versa, fill the poly with some patterns and change the pen size. 
Moreover you can copy the current poly in the clipboard and, 
because desk accessories are supported, you can then paste it in 
to those of them accepting picts or in other applications. Of 
course you can print the current poly on any printer you wish and 
setting the pen scaling factor for PostScript printers will allow a 
much more accurate definition for the pen width like drawing 
hairlines as thin as possible on the currently attached device. For 
example a pen size of 3 with a scaling factor of 300 dpi will cause 
lines to be printed at a width of 1/100 of an inch (3 * 1/300) which 
on a laser writer's raster memory will be exactly 3 pixels. 

Although the program only serves as a demo its routines 
have been designed to be fast and compressed in order to be 
perfectly usable in a larger project. For example the actual 
procedure in charge of smoothing an input poly can be consid- 
ered like a Toolbox routine for its speed and compression. You 
could even be disinterested in how this routine works (of which 
a full discussion would go beyond the scope of this article), and 
you could just call it from your program passing the right 
arguments like you would do with any Toolbox proc. Seemingly 
the routine that builds a special polygon (*MakePoly") can be 
easily used from a different application even if dealing with 
hundreds of smoothed polys instead of the only one we can have 
in the demo. Points where potential problems may arise have 
been marked and a short description of the possible bug is given. 
This, of course, is done not for carelessness but because a lot of 
code would have been needed and we couldn't take up any more 
space. Assembly language has been chosen mainly for its insu- 
perable speed since we all experienced what it means in terms of 
time to scroll a certain number of smoothed polygons in a 
window. Furthermore having to deal with compressed data 
structures makes it much easier to control them in this language. 
Macros have been used for comments dividing them in short and 
long as in the picture's opcodes. Routines that refer more closely 
to the subject of this article, as you have seen, have already been 
shown ina pseudo high-level language. Hierarchical menus have 
been used where appropriate and the new PrGlue Toolbox trap 
(in 256K ROMs and in system 4.1 or later) is used for printing 
code. 

I hope this discussion saved you some time in implementing 
comments in your applications. Please note that despite most of 
the information being presented in this article is not documented 
anywhere else, it is not a weird approach to accomplish the work 
done but just the way things are at the moment and probably will 
be for a while. 

Besides the following documentation MacsBug was of 
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invaluable help as usual. 
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Listing: Smooth.Link 
[Output Smoother 

/Туре ‘APPL’ ‘DEMO’ 
/Bundle 

Smooth 


/Resources 
SmoothRes 


/End 


Listing: Smooth.asa 


- Smoother: picCommenting polygons & non solo 
; - Raul Tebesso - via delle Isole 23/А - 00198 ROMA --- 


; 
; 
д 
; WARNING: because this ргодгат is intended as а demo, there 
; аге some circumstances where a stronger error checking 

; Should be applied. Due to this, situations where а 

; potential problem may arice, 

; ere marked with а (6) symbol and а short advice is given. 
I 


nclude Inside comments:SmoothSource:Traps.D 
MBarHeight EQU  $8AÀ 
DoubleTime EQU  $2FØ 


GENERAL EQUATES 


screenBits EQU  $FF86 
PortRect EQU 16 
PrGlue EQU АВЕО |Мен print manager call 
РгОреп EQU %С8000000 ;PrGlue’s routine selec- 
tors 
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PrClose EQU %00000000 

PrintDefault EQU  $20040480 

PrStlDialog EQU . $24040484 

PrJobDialog EQU %32040488 

PrOpenDoc EQU $04000C00 

PrCloseDoc EQU $028000484 

РгОрепРаде EQU — $10000808 

PrClosePage EQU — $1800040C 

PrPicFile EQU %60051480 

PrError EQU %68Ү000000 

iCopies EQU 4 ¿Print Manager Stuff 
prInfo EQU 2 

prJob EQU 62 

rPage EQU 6 

bJDocLoop Е 6 

PicDwgBeg EQU 130 ;PicComment Kinds 
PicDwgEnd EQU 131 

PolyBegin EQU 160 

PolyEnd EQU 161 


PolyIgnore EQU 163 
PolySmooth EQU 164 
PicPlyClo EQU 165 
SetLineWidth EQU 182 


Frame EQU 1 ;PolyVerbs 
Fill EQU 2 

Close EQU 4 

; — MACRO 

MACRO prExec Rout ineSelect = 


MOVE.L *t (RoutineSelect),-CSP) ;routine selector on stack 


r^" Ргб1ие ¿execute trap 
MACRO ShortComment Kind = 

MOVE.W 8 (Kind), -CSP) 

CLR.W -CSP) 

CLR.L -CSP) 

oe 
MACRO LongComment Kind,Size,Hand = 


MOVE.W ®(Kind),-CSP) 
MOVE.W t (Size), -CSP) 
MOVE.L (Hand),-CSP) 
p S 


MACRO — CheckItm MHandle,Item s 
MOVE.L (MHandle)(A52,-CSP) 
MOVE.W (Item),-CSP) 


ST -(SP) ; check 
pousse 
MACRO — UnChkItm | MHandle,Item = 


MOVE.L (MHandle)CA5),-CSP) 
MOVE.W (Item),-CSP) 

CLR -(SP) 

ne 


juncheck 


; —— Register usage 
PolyHand EQU А4 
BSR InitGlobals 

BSR Ini {Мас 

BSR GetHandles 

BSR SetMenus 

BSR SetWindow 

BRA NewPoly 


;Do not rearrange the 
jorder of these subs 


зілі one 
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бо 


) 
Тг 


Do 


De 


Up 


eg 


01 


; 
Мо 


ор -SystemTask 
CLR.W -CSP) 

MOVE.W '$FFFF,-CSP) 

PEA EVENTRECORDCA5) 
_GetNextEvent 

MOVE.B CSP2*,D0 

BNE.S DoEvent 

TST.W whileDrawing(CA5) 
BNE.S TrackLine 

BRA.S Loop 


;Every event 


¿Check if we have to.. 
;Idle line 


Event 
CMP .W 
BEQ MouseDown 
CMP.W 83,00 

BEQ KeyDown 
CMP.W 86,00 

BEQ UpDate 
CMP.W 88/00 

BEQ DoAct 
BRA.S Loop ¿we don’t support other events 


ackL ine 

РЕА СигРоіп(ХА5) 
_GetMouse 

MOVE.L CurPointCA5), DØ 
CMP.L OldPointCA52,D0 
BEQ.S Loop 


MOVE.W ИНАТСА5 2,00 
81,00 ;is mousedown ? 


jis keydown ? 
;is update ? 


;is activate ? 


;Did we move since lest time ? 


¿we ere in XOR mode 
MOVE.L LestPoint(A52,-CSP) ;start Pt 
-MoveTo 
MOVE.L OldPoint(CA5), -CSP) 
-LineTo 
MOVE.L LastPoint(A52,-CSP) ;draw new line 
-MoveTo 
MOVE.L CurPointCA5),-CSP) 
-.LineTo ` 
MOVE.L CurPointCA5),01dPointCA5) 
BRA.S Loop 


;overwrite old line 


;c'est la vie 


Act MOVE .W MODIFYCA52,D0O 
BIST 380,00 

BEQ.S DeAct 

MOVE.L MESSAGECA5), - CSP) 
-SetPort 

BSR DimMenu 

BSR PutGrow 

BRA LOOP 

Act BSR  ActMenu 
PEA GrowBox(CA5) 
_EraseRect 

BSR PutGrow 

BRA LOOP 


jActivate or deactivate 


уме only support copy menu 


;clean it and 
,draw inactive 


Date 

MOVE.L TheWindCA5), -CSP) 
-BeginUpdate 

TST.W PoluDrawn(A5) 
BEQ.S 80 

BSR ReDraw 

BRA.S @1 

TST.W WhileDrawingCA5) 
BEQ.S @1 ;Exit if we are not either drawing 
BSR — DrewPoly ;Redrew part already drewn 
MOVE.L LastPoint(A52,-CSP) ;redrew idle line  _МоуеТо 
MOVE.L OldPoint(A52, -CSP) 

-LineTo 

BSR  PutGrow 

MOVE.L TheWindCA5), -CSP) 

-EndUpdete 

BRA LOOP 


;branch if no poly 
¿show poly 


useDown 
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;Allow complete edit menu for DA 


CLR.W -CSP) 

MOVE.L WHERECA5D), -CSP) 

РЕА WINDOWCA5) 

-FindWindow 

MOVE.W CSP2*,DO 

MOVE.W 00,03 

ADD.W 00,00 

MOVE.W WTABLECPC,D0 .W),D0 

JMP WTABLECPC,D9 .W) 
WTABLE DC.W  LOOP-WTABLE 

DC.W  DoMenu-WTABLE 

DC.W  SysEvnt-WTABLE 

DC.W DoContent-WTABLE 

DC.W  DoDrag-WTABLE 

DC.W  DoGrow-WTABLE 

DC.W  Loop-WTABLE 

DC.W  DoZoom-WTABLE 

DC.W DoZoom-WTABLE 


¿needed for zoom box 


J 

KeyDown CLR.L -(SP) 
MOVE.W MESSAGE*2CA5), -CSP) 
-MenuKey 
MOVE.L CSP)+,MENUCAS ) 
BRA.S ExMenu 


DoMenu 

CLR.L -CSP) 

MOVE.L WHERECA5),-CSP) 

_MenuSe lect 

MOVE.L CSP)+,MENUCA5) 
ExMenu  CLR.W -CSP) 

-HiliteMenu 

MOVE .W МЕМОСА5 ), DØ 

CMP.W 84/00 

BLE.S eg 

SUB.W 8’А’-4-1,00 ;Allign Submenu item-60 (65-4-1) 
@ZADD.W 00,00 

MOVE.W MTABLECPC,DO .W),DO 

JMP MTABLECPC, DO .W) 
DC.W LOOP-MTABLE 
DoMela-MTABLE 
DoF i le-MTABLE 
DoEdit-MTABLE 
DoDo-MTABLE 
DoPensize-MTABLE 
DoPat-MTABLE 
DoPenscale-MTABLE 


;Hilite off 


;is а submenu ? 


¿Menus 


DC.W 
DC.W 
DC.W 


;Submenus 


DoContent 
CLR.L -CSP) 
-FrontWindow 
MOVE.L CSP2*,D0 
СМР.  WINDOWCA52,DO 


BEQ.S 60 ;Already in front 
MOVE.L WINDOWCA5), -CSP) 
-SelectWindow 
egBSR — ChkDoubClick ¿set DoubleClickCA5) accordingly 


MOVE.L WHERECA52,MousLoc(CA5) 
РЕА MousLoc(A5) 
_GlobalToLocal 


TST.W PolyDrawnCA5 > 
BNE Loop 

TST.W whileDraewingCA5) 
BNE  AddPoint 

BRA = PolyInit 


;do we have а poly yet ? 
;уез, no action implemented 
Мо, is it initialized yet ? 


‚№, start а new one 


7 

DoDrag MOVE.L WINDOWCA52, -CSP) 
MOVE.L WHERECA52, -CSP) 
PEA . WBounds(CA5) 
-DragWindow 
BRA LOOP 


DoGrow  CLR.L -(SP) 


;yes, one more line for the poly 


6 7 


MOVE.L УТМООМСА5 >, -CSP) 
MOVE.L WHERECA5), - CSP) 
РЕА WSize(A5) 

—GrowW indow 

MOVE.L (SP)+,D0 

BEQ LOOP jLaizy, if not grown 
MOVE.L WINDOWCAS >, -CSP) 

MOVE .L 00,-(ӨР) 


ST -(SP) 
-SizeWindow 
РЕА GrowBoxCA5) 
-EreseRect jErase it and 
РЕА бгомВохСА5) ¿put it in the update гоп 
-InvalRect 
ResetWnd BSR  CalcGrow 
BSR — ClipWind 
BSR — Put6row 
BRA LOOP 
CLR.W -CSP) 


DoZoom 
| MOVE .L WINDOWCA5), -CSP) 
MOVE .L WHERECA5), - CSP) 
MOVE .W D3, -CSP) 
_TrackBox 
TST.W CSP)+ 
BEQ LOOP 
MOVE .L WINDOWCA5), Аб 
РЕА PortRectCAd) 
-EreseRect 
CLR.W -CSP) 

MOVE.L WINDOWCA5),-CSP) 
MOVE .W D3,-CSP) 


;PartCode in or out 


j;PartCode іп or out 


SF -(5Р) 
—ZoomW indow 
BRA ResetWnd 


7 

SysEvnt PEA  EVENTRECORD(A5);make system happy 
MOVE.L WINDOWCA5), -CSP) 
SystemC 1 ick 
BRA LOOP 


Polynit 
MOVE .L MousLoc(CA5), -CSP) 
-Moveto 
MOVE.W 3119, -CSP) 
-PenMode 
MOVE.L 8%10001,-(5Р) 
-PenSize 
MOVE.W 81, NumPointsCA5) 
MOVE.L CPolyHand), Аб 
MOVE .L MousLoc(A5), (Аб) 
MOVE .W 84 BytesWrittenCA5) 
ST whi leDrawing(A5); follow mouse movement with a line 
MOVE.L MousLoc(A5),LastPoint(A5) ;init points 
MOVE .L MousLocCA52,01dPoint(CA5) 
BRA Loop 


¿Start poly 


ХОК mode while drawing poly 


;Реп 1,1 
¿First point 


write it in the list 


AddPoint 
TST.W DoubleClickCA5) 
BNE — ClosePoly 
MOVE.L LastPointCA5),-C(SP) 
-MoveTo 
MOVE.L OldPoint(A5),-CSP) 
-LineTo 
_Реп№ гта] 
MOVE.L LastPointCA5),-CSP) 
-MoveTo 
MOVE .L MousLoc(45), - (SP) 
-LineTo 
MOVE.W #10, -CSP) 
-PenMode 
BSR . DoAdd 


,user wants to close the poly ? 


;cleer last line 


;Reset pen 
‚ада new line 


;put back XOR mode 


¿put new point into the list 


68 


CMP.W %32768,BytesWrittenCA5) 
ВР. ClosePoly 
BRA Loop 


¿Do not write past block 
¿force to close in case 


) —r cm 

; Peck ‘MousLoc’ into compressed poly data list : 

; A negative word signals а short delta; а word es follows.. 
; / bit 15 always set / bits 14-8 = dy (764,63) / bits 7-0 = 


d 
; 
; 
; 
; 
; 
0 


WordPoint 


LongPoint 


X 


0 


(-128, 127)/ A positive word signals а 4 bytes point (Y & X) 
es usual WARNINGCé2: this scheme won’t work if high bit of 
point is negativeCif а Y becomes «0 а point will be 
interpreted as а short offset) 


Add ADDQ.W #1, NumPoints(A5) 
MOVE.L (PolyHand), Ag 
ADDA.W BytesWritten(A5), Аб 


jone more point 
¿Pointer in Ад 
;get to mark 


MOVE.W Моџѕі осСА5 ),00 jcurrent Y 
SUB.W LastPoint(A5),D0 00 = Delta Y 
CMP.W *63,D0 Оу must be in the range 
BGT.S LongPoint ;doesn’t fit 
CMP.W #-64,00 
BMI.S LongPoint 

;Y fits, now check X 
MOVE .W MousLoc*2(A52,D1 ;current X 
SUB.W LastPoint+2CA5),D1i ;01 = Delta X 


CMP.W #127,D1 

BGT.S LongPoint 
CMP.W #-128,01 
BMI.S LongPoint 


ду in а signed byte range ? 


¿Word format Point (compressed) 
;only 2 bytes for а short offset 
¿force а negative word to signal 
¿write Y offset 

¿write X offset 


ADD.W #2,BytesWrittenCA5) 
BSET %7,00 

MOVE.B 00,(А02% 

MOVE.B 01, (Аб) 

ВКА.$ AddDone 

¿Long format (normal) 

ло an offset, a Point 
,8lways positive in our plane 


ADD.W #4 ButesWritten(A5) 
MOVE.L MousLoc(A5),(A0) 


AddDone 


MOVE.L MousLoc(A5),LastPoint(A5) ;update 
MOVE.L MousLoc(A5),01dPointCA5) 
RTS 


ClosePoly 


ST PoluDrawn(A5) 
CLR.W whileDrawing(A5) 
_Реп№ гта] 

MOVE .L DoHandCA5), -CSP) 
MOVE.W #1, -CSP) 
-EnebleItem 

MOVE.L FileHandCA5), -CSP) 
MOVE.W 83,-(5Р) 
-EnableItem 


Poly is now completed 
уме ere through 
preset mode and size 


,8allow unsmooth/smooth 
запа print 


MOVE.L CPolyHand), Аб ;Pointer in Аб 
MOVE.L CAB),MousLoc(A5);save extra code simulating a click 


BSR DoAdd jat lest point (MousLoc) = first 
-OpenRgn WARNING :(6) should make sure our poly is not 
BSR DrawPoly з too big to fit in a region. 
MOVE.L RgnHand(A5),-(SP) ;if it doesn't fit, we are dead 
-CloseRgn 
BSR — SetPen 
BSR CleanWind 
BSR ReDraw ;Show poly 
BRA Loop 

DoMela 


CMPI.W #2, MENU+2(A5 ) 
BGT 61 
;show about dialog 


CLR.L -CSP) ;space for result 
MOVE .W #256,-CSP) ; 1D 
CLR.L -CSP) ;NIL storage 
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MOVE.L #-1,-CSP) 
-GetNewDialog 
MOVE.L CSP2*,A2 
@ZCLR.L -CSP) 
PEA ItmHitCA5) 
-ModalDialog 
CMP.W #1, ІТМНІТСА5) 
BNE.S 00 
MOVE.L A2, -CSP) 
-DisposDialog 
BRA LOOP 


jin front 


61MOVE.L MeleHandCA52,-CSP) ;Get DA 
MOVE .W MENU*2CA5), -CSP) 
PEA DskNameCA5) 


-GCetItem 
CLR.W -(SP) 
РЕА DskhName(A5) 
_OpenDeskAcc 
MOVE.W CSP2*,D0 
BRA Loop 
DoF ile 
MOVE.W MENU+2CA5 ), DØ ¿Item Num 
ADD.W 00,00 


MOVE.W MITABCPC,D0 .W2,DO 
ЧМР МІ1ТАВСРС, 00.9) 
МІТАВ DC.W — LOOP-M1TAB 

DC.W  NewPolg-M1TAB 
DC.W PageSetup-M1TAB 
DC.W  Print-M1TAB 
DC.W — LOOP-M1TAB 

DC.W  Quit-M1TAB 


jLaser Pen Menu 


А 

DoEdit 
CLR.L -CSP) ;Check if DA in front 
-FrontWindow 


MOVE.L CSP2*, Аб 

CMP.L TheWindCA5), Ag 
BEQ DoScrap 

CLR.B -CSP) 

MOVE.W MENU+2(A5 ), -CSP) 
SUBQ.W #1, CSP) 

_SysEdit 

TST.B CSP)+ 

BRA LOOP 


¿branch if our wind in front 
;System Wind Frontmost 


¿balance different numbering 


,get rid of bool 


NewPoly 
CLR.W РоТуОганп(А5) 
CLR.W  WhileDrawingCA5) 
CLR.W NumPointsCA5) 
CLR.W LiscioCA5) 
MOVE .L DoHandCA5), -CSP) 
MOVE.W #1,-CSP) 
PEA ‘Smooth’ 
-SetItem jreset 
MOVE .L DoHand(CA5), - CSP) 
MOVE.W 81,-CSP) 
-DisebleItem jno smooth menu and 
MOVE.L FileHand(A52,-CSP) ;no print active 
MOVE .W 83,-(5Р) 
-DisableItem 
BSR — CleanWind 
BRA Loop 


;clear poly 


¿no poly, no smooth 
¿Menu Handle 


д 
PageSetup 
prExec PrOpen 
BSR СһескЕгг 
CLR.W -CSP) 
MOVE.L PrintRecCA5),-CSP) 
prExec PrSt1Dialog 
MOVE.W CSP2*,00 
ргЕхес PrClose 
BRA Loop 


;ореп the driver 
¿driver ok 
jStyle Dialog 


¿forget it 
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MOVE .L 03, -CSP) 

РЕА . SavePort(A5) 
-GetPort 

prExec PrOpen 

BSR СһескЕгг 


¿save 03 
;Зауе current port 


¿open the driver 


CLR.W -(SP) 

MOVE.L PrintRec(A5),-CSP) 
prExec PrJobDialog 

MOVE.W (5Р2%,00 

BEQ PrintDon 


,ob Dialog 


; cance led? 


BSR OroCurs 

CLR.L -CSP) 

MOVE.L PrintRecCA5), -CSP) 
CLR.L -(SP) 

CLR.L -CSP) 

ргЕхес PrOpenDoc 

MOVE.L CSP)+,PrintPortCA5) 
BSR CheckErr 


¿put watch curs 
;Open Print Port 


¿problems? 


MOVE.L PrintRec(A5),A0 
MOVE.L CAD), АВ 

PEA ргіпГозграде(А0) 
-ClipRect 


,Initialize New Graph Port 


MOVEQ 81,03 
MOVE.L PrintRecCA5), Ad 
MOVE.L (Аб), Аб 
TST.B prJob*bjDocLoop(A) ;Check if Draft or Spool 
BNE.S e1 
MOVE.W ргЈоб+іСоріеѕСАб ),03;5еї Num copies if Draft 

@1SUBQ.W 81,03 ;for DBRA 


,8ssume Spool 


PageLoop 
MOVE.L PrintPortCA5),-CSP) ;get ready to draw 
CLR.L -CSP) 
prExec РгОрепРаде 
BSR СһескЕгг 


пен page 
‚аге we ok? 


MOVE.L CurPen(CA5), -CSP) 
-Репбіге 

MOVE.L CommentHand(A5),A1 ;scaling 

MOVE.L (А12,А0 ,deference handle 
MOVE.W #12, (Аб)+ ,humerator = 72/6 and.. 


;Set size and.. 


¿driver opened successfully ? 


MOVE.W CurScaleCA52,CAQ)  ;denominator in dpi/6LongComment 


SetL ineWidth,4,A1 
BSR МакеРо]у 90 it 
MOVE.L PrintPortCA52,-CSP) 


prExec PrClosePage ;page done 
BSR СһескЕгг 
DBRA — D3,PageLoop ¿next page 


MOVE.L PrintPortCA5),-CSP) 
prExec PrCloseDoc 
BSR CheckErr 


¿document done 


MOVE.L PrintRecCA52, Ad 

MOVE.L (АВ), Аб 

TST.B prJob*bjDocLoopCA8) ;Check if Draft ог Spool 
BEQ.S PrintDon ;Branch if draft 


MOVE .L PrintRecCA52,-CSP) ;5роо1 to printer 
CLR.L -CSP) 

CLR.L -CSP) 

CLR.L -CSP) 

РЕА  PrStatus(A5) 
prExec PrPicFile 
BSR  CheckErr 


¿print spool file 
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PrintDon prExec PrClose 
MOVE.L SavePortCA5), -CSP) 


;close driver 


-SetPort ;restore port 
MOVE.L CSP2*,D3 ¿register and 
-InitCursor ¿arrow curs 
BRA Loop 


CheckErr CLR. -CSP) ;WARNING C¿) 
prExec PrError ;if әп error occurs we have no handler 
MOVE.W CSP)+, DØ ,Err code іп 00 


BNE Error ;this just goes to the finder 
RTS 
Quit — .ExitToShell :ciao 
DoScrap 
TST.W PolyDrawnCA5) 
BEQ Loop ¿nothing to clip 


PEA WRectCA5) (6) Not a correct rect 


-ClipRect ¿it's here just to save code 

CLR.L -CSP) 

PEA WRectCA5) ;(6) should use а better rect 

_OpenPicture ;С2) Do we have enough mem for a pict? 

MOVE.L CSP )+, А2 ;PicHandle 

Shor tComment PicDwgBeg ;ges, it’s the format you know 
BSR MakePoly ‚бо it 


ShortComment PicDwgEnd 
-ClosePicture 


BSR — ClipWind 
CLR.L -CSP) 
_ZeroScrap 
MOVE.L (5Р2%,00 
BNE Error 
MOVE.L А2,А0 
_GetHand1leSize 
СІВ. -CSP) 
MOVE.L D@,-CSP) 
MOVE.L t PICT^,-CSP) 
MOVE.L CA2),-CSP) 
-PutScrep 

MOVE.L CSP2*,D0 
BNE Error 
MOVE.L A2,-CSP) 
-KillPicture 

BRA Loop 


;restore clip 


;how big is the pict 


j lenght 
;ResType 
;Ptr Pict 
put it down 


;Get rid of it 


DoDo ¿Smooth or unsmoooth 
MOVE.L DoHand(CA5), -CSP) ¿Menu Handle 
MOVE.W #1, -CSP) ¿item num 
NOT.W LiscioCA5) ¿set & check Smooth flag 
BEQ.S 00 ¿branch accordingly 
LEA DrawSmooth(PC),A3 routine to call in АЗ 
PEA 'Unsmooth" ; load proper name 
BRA.S 61 
еді ЕА OrewPolyCPC2, АЗ 
РЕА ‘Smooth ’ 
@1_SetItem 
-OpenRgn 
JSR (АЗ) 
is not 
MOVE.L RgnHandCA5), -CSP) 
-CloseRgn 
BSR CleanWind 
BSR ReDraw 
BRA Loop 


¿no smooth 


¿WARNING :(6) should make sure our poly 


;too big to fit in а region 
;if it doesn't fit, we ere dead 


7 

DoPensize 
UnChkItm PenHand,CurPen(A5)  ;uncheck old 
MOVE .W MENU+2CA5), CurPenCA5) jv 
MOVE .W MENU+2CA5 ), CurPen*2CA5) jh 
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CheckI tm PenHand,CurPenCA5) ;сһеск new 
TST.W PolyDrawnCA5) 


BEQ Loop 
BSR  SetPen 
BSR CleanWind 
BSR Redraw 
BRA Loop 
DoPat 
UnChkI tm FpatHand,ChkPat(A5) ;uncheck old 


MOVE .W MENU*2CA5), ChkPatCA5) 

CheckI tm FpatHand,ChkPat(A5) ;сһеск new 

MOVE .W MENU*2(A52,D0 

SUBQ.W * 1,00 

ADD.W 00,00 

MOVE.W PatTabCPC,D£ WD, CurPatCAb) ;get offset constant to 
PAT 

TST.W PolyDrawnCA5) 


BEQ Loop 

BSR CleanWind 

BSR ReDraw 

BRA Loop 
PatTeb DC.W -8 ;White 

DC.W -32 ;LtGray 

DC.W -24 ;бгау 

DC.W -40 ;Окбгау 

DC.W -16 ;Black 
DoPenscale 

UnChkI tm PscaleHand,Chkscale(A5) „uncheck old 


MOVE .W MENU+2(A5 ), ChkscaleCA5) 


CheckI tm PscaleHand,ChkscaleCAb) ;сһеск new 
MOVE .W MENU+2CA5), DO 
SUBQ.W 81,00 
ADD.W 00,00 
MOVE .W SclTabC(PC,D@.W),CurScaleCA5) ;get scale factor 
BRA Loop 

SclTab ;unsign byte values (8-255) 
DC.W 12 ; 12/6 
DC.W 25 ; 150/6 
DC.W 50 ; 300/6 
DC.W 100 , 600/6 
DC.W 200 ; 1200/6 

SetPen 
TST.W WhileDrawing(A5) ;don’t change pen if drawing poly 
BNE.S 00 
MOVE.L CurPen(A5), -CSP) 
-PenSize 

egRTS 

Redraw ¿no poly to work with 
TST.W CurPatCA5) ;is our poly filled ? 
BEQ.S 00 ;No fill if CurPat=0 


BSR  FillPoly 
@OTST.W LiscioCA5) 

BNE.S DrawSmooth 
DrawPoly 

MOVE.W NumPointsCA52,D4 

SUBQ.W #2,D4 ;Sub 1 for DBRA and 1 for _Moveto 

BGT.S eg ;check reasonable poly O2 points) 

RTS ;return if not to consider а poly 
@QMOVE.L PolyHend, Аб  ;No surprise 

-HLock ;Line and LineTo can cause relocation 

BNE Error 

MOVE.L CPolyHand), АЗ 

MOVE.L CA3)+,-CSP) 

-MoveTo 
NextLine 

TST.W (АЗ) 

BPL.S LongPt 


;is poly smoothed ? 


¿Total num of points 


;Pointer to Poly data 
¿first point 


;Check for bit 15 (sign) 
;IF set do Long ELSE do Short 


ShortPt MOVE.B CA32*,D1 


;dY: а signed 7 bits 
offset 
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BIST #6,D1 ¿Test sign bit:a negative offset ? 


BNE.S 80 ез, flag bit can stay 

BCLR 87,01 ¿else Cif positive) clear it 
egEXT.W 01 ДҮ as а word 

SWAP 01 jin hi word 01 now 

MOVE.B CA3)+,D1 ¿signed byte dx 

EXT.W D1 ;dx in low word 

MOVE.L D1,-CSP) ¿offset on stack 

Line ¿draw to 

BRA.S Мхіл 


LongPt MOVE.L CA3)+,-CSP) 
-LineTo ,8 point 
NxLn DBRA D4,NextLine 


MOVE.L PolyHand, Ай 
-HUnLock 

BNE Error 

RTS 


¿free again 


DrawSmooth 
BSR — UnPackPoly уме need normal points to work 
MOVE.L PolyBufferCA5),A@ jour temporary poly 
-HLock 
BNE Error 
MOVE.L PolgBufferCA52,A0 
¿Emulating a High-Level call 
MOVE.W NumPointsCA5),-CSP) ;First param 
MOVE.L (А0),-(5Р) ;second, a Ptr to points list 
BSR — SmoothPoly ;fortissimo 


MOVE.L PolyBuf ferCA5), Ad 


-HUnLock ;free again 
BNE Error 
RTS 


; SmoothPoly CNumPt: INTEGER; PtrPolyList:PTR) 

; Сё) Implementation good for poly side«1024 pixels of length 
; Тһе resulting smoothed polygon closely resembles the laser 
output 


LineTo EQU $91 ; trap num 
; —— Stack Frame 

7 

NumP t EQU 12 
PtrList EQU 8 
ParamBytes EQU 6 

А EQ -2 

В EQU -4 

Ау EQU -6 

Ву EQU -8 

X EQU  -10 

Y EQU -12 

Line EQU -16 
0104 EQU -18 
0140 EQU -20 


The following із а Basic translation of the algorithm 
Comments іп the Asm source refer to these integer variables 
Note that the two version slightly differs where necessary 
PCc,n) is а bidimensional array of points: 

P(@,n)=Y P(1,n)=X ; n=point index 


X1=PC1, 12-PC1,02: Y 1=PCB, 1)-PCO, 0) 

X=X 1\2+РС1,0):Ү=Ү 1N2*PC0, 0) 

MOVETO X,Y 

FOR )-1 TO NumPt 
X0-X1:Y0-Y 1 
X1=PC1, ]+1)-РС1, j2:Y I-PC0, j* 1-PC0, 32 
T=CABSCX 1+Х0 )+АВЅСҮ 1+Y¥8))\8 


Wwe We We We We We We We We We e We We BW 
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› 
; 
P 
; 
‚ 
; 
7 
7 
; 
; 
; 


‚ LINETO А,В 
МЕХТ 

МЕХТ 
LINETO Х,Ү 

SmoothPoly ¿If called from hi level think of it 
LINK A6,*Locals ¿like а ToolBox procedure 
MOVEM.L А1-А4/00-О7,-(ӨР) 
MOVE.L PtrListCA62,A4 
MOVE.W 81 іпеТо,00 ;Тгар num for LineTo 
_GetTrapAddress 
MOVE.L Аб, АЗ ¿store іп АЗ for later use 
CLR.L BvCA6) ¿clear last drawn point 
MOVE.L СА4),04 ;First Pt 
MOVE.L 4(А4),05 ¿second Pt 
SUB.W 04,05 ;X1 
MOVE.W D5,D1 ¿safe in 01 
SWAP 04 ¿push y in low word 
SWAP  D5 
SUB.W D4,D5 ;Y1 
MOVE.W 05,00 safe in DØ 
ASR.W 81,D1 
ASR.W 81,00 
ADD.W 04,09 ;DØ=Y+(Y2-Y 1)/2 
ADD.W 2(А4),01 ;D1=X+(X2-X1)/2 
MOVE .W DØ, YCA6) 
MOVE.W D1, XCA6) 
MOVE.W D1,-CSP) 
MOVE .W 00,-(ӨР) 
-МоуеТо 
SUBQ.W #1, NumPt(A6) ;ready to start 

Nex tPoint 
MOVE .L 05,04 ;Y0=Y1 : X0-X1 
ADDQ.L #4, А4 ;CurrentszNext 
MOVE.L 4(А4),05 ¿Next Point in 05 
SUB.W 2(А4),05 ,X1-NextX-CurX 
MOVE.W 05,06 ¿safe in D6 
SWAP 05 ;push Y down 
SUB.W (А4),05 ;Y 1=NextY-CurY 
MOVE.W 05,00 ,safe in DØ 

f Calc num iteration now (T) 
ADD.W 04,00 ;DØ=YØ+Y 1 
BPL.S 61 
NEG.W DØ ; ABS 

@1SWAP 04 Хх in low word 
ADD.W 04,06 ;06=Х0+Х 1 
ВРІ .5 62 
NEG.W 06 ; ABS 

@2SWAP D4 ;у back in low 
ADD.W 00,06 ;06=(09^2+06-2) 
LSR.W 83,06 ; T=D6\8 (step) 
CMP.W 82/06 1-22 at least 
BPL.S 00 


IF Т<2 THEN T=2 
Z=T*T*2:Du=T+! 


FOR п-0 TO Т 


Du=Du- 1:Q=n*n:w=Du*Du 
A=(Q*X 1-w*X0) /2*PC 1, 3) 
BzCQ*Y 1-w*Y0) /2*PC0, j) 


MOVEQ #2,06 


@OMOVE .W 06,07 


Cu 


MULU 07,07 
LSL.W #1,D7 
MOVEQ #0,D3 


MOVE .W 06,00 
ADDQ.W 81,00 
MULU 00,00 


MOVE.W D0,01dWCA6) 
MOVE.W #1,01dQCA6) 


гуа 


;M point list Ptr 


¿save some cycle 


;divs by 2 with no sign loss 


¿save the world 


;First point recorded for closing 


;1=06 
;T*T 
;2=07 (T*T*2) 
¿n=0 


зілі values 
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MOVE.W 06,00 ;Са1с W (ТҰТ), avoiding slow MULU DBRA 00,5расса 


ADD.W 00,00 BRA.S SpacDon 
ADDQ.W 81,00 @OMOVE .L -4(АВ), САЙ) ;point to add the offset to 
SUB.W D0,01dWCA6) ¿W=(01dW)-2T+1 MOVE.B CA1)+,01 ;dY: a signed 7 bits offset 
MOVE.W O1dWCA62,D0 BTST  86,D1 ‚а negative offset ? 
BNE.S 61 ;yes, flag bit can stay 
MOVE .W 03,01 ;Calc Q (пп), avoiding slow MULU ВСЕ 87,01 positive: clear flag bit 
ADD.W 01,01 e1EXT.W 01 ЖҮ as а word 
SUBQ.W 81,01 ADD.W D1,CA0)0* 
ADD.W D1,01dQCA6) :0-(01002%2-1 MOVE.B (А12%,01 ;signed byte dx 
MOVE.W 01dQCA6),D1 EXT.W 01 ;dx in low word 
ADD.W D1,CA0D* 
ADDQ.W 81/03 ;п=п+ 1 DBRA 08, Зрасса 
SpacDon RTS 
MOVE.W 00,02 ;Calc B — j #s====s===========s====================s==================== 
MULS 04,02 ;Y0*W FillPolu 
MOVE.L D2,A2 MOVE.L RgnHand(A5),-(SP) ;0уг Handle 
MOVE.W D1,D2 MOVE.W CurPat(A5),D0 ;Offset to pat 
MULS 05,02 ;Y1*Q MOVE.L (A52,A0 ‚Ріг to 0075 GlobalsPEA 
SUB.L А2,02 0CA0,D0 .W) fill it with Current Pat 
01/5 07,02 2/7 -FillRgn 
ADD.W (А42,02 ;* CurPt Y RTS 
MOVE.W D2,BCA6) safe j 
CleanWind 
SWAP 04 ;push Xs down MOVE.L TheWind(A5),A0 
SWAP 05 РЕА . PortRect(A0) 
-EreseRect 
MOVE .W 00,02 Calc А — BSR X PutGrow ;show it 
MULS 04,02 ;X0*W RTS 
MOVE.L 02,А2 3 
MOVE.W 01,02 ClipWind 
MULS 05,02 ,X1*Q MOVE.L TheWindCA5), Ad 
SUB.L А2,02 PEA PortRectCA®) 
DIVS 07,02 2/7 -ClipRect 
ADD.W 2(А4),02 jt CurPt X RTS 
MOVE.W 02,АСАб) ¿save ; 
SWAP 04 PutGrow 
SWAP 05 MOVE.L 8%10001,-(5Р) 
-PenSize ;Use pen 1,1 to draw 
CMP.W AvCA62,D2 ;did we move? Cover the unit) MOVE.L TempRgnCA52,-CSP) ;save 
BNE.S 00 ¿much fester to check it here, than go -GetClip 
MOVE.W BCA62,02 ; through the ROM with a useless Lineto PEA GrowBox(A5) ;only the box 
CMP.W BvCA62,D2 -ClipRect 
BEQ.S 61 MOVE.L TheWindCA5), -CSP) 
-DrewGrowIcon 
egMOVE .L BCAG), -CSP) MOVE.L TempRgn(A5),-(SP) ;put back 
JSR (A3) ;LineTo -SetClip 
MOVE.L BCA6), BvCA6) BSR SetPen ¿restore pen 
@1DBRA 06, Сигуа RTS 
7 
SUBQ.W 8 1, NumPt CAO) CalcGrow 
BGT  NextPoint MOVE.L TheWindCA5), Ad 
LEA — GrowBoxCA52,A1 ;Recalculate new GrowBox 
Done MOVE.L YCA6),-CSP) ;back to first point MOVE.L PortRect*4CA0)2, CA1) ;push bottom right point of 
JSR CA3) ;LineTo window 
SUB.W &]5, (А1)+ ¿make Top left box 
MOVEM.L (SP)*,A1-A4/00-D7 ;restore the world SUB.W 8]5,(А1)+ 
UNLK Аб MOVE.L PortRect*4CA02, СА1) ;end bottom right 
MOVE.L СЅР )+, Ad ;RIS RTS 
ADDQ *ParamBytes, SP E 
JMP (АЙ) ;back home ChkDoubC1 ick ;Check if а double click 
у дд CLR.W DoubleClickCA5) ;assume not 
UnPackPoly MOVE.L WHENCA5),D1 ¿this click 
MOVE.L PolyBufferCA52,A0 — ;copy the poly here SUB.L LastClick_T(A5),D1 ;ticks elapsed since last 
MOVE.L (Аб), Аб ‚Ріг to temporary space CMP.L DoubleTime,D1 ;close enough togather? 
MOVE.W NumPointsCA52,D0 BCT.S e ¿branch if over 'DoubleTime* 
MOVE.W BytesWritten(A5),D1 MOVE .М WHERECAS ), DØ ¿now check for position 
MOVE.L CPolyHend2,A1 ;Ptr to packed poly in A1 SUB.W LastClick_WCA5),D8 ;delta Y 
MOVE.L CA1)+, (А 2% ;first point BPL.S 61 ; ABS 
SUBQ.W 81,00 ¿one pt processed NEG.W DØ 
MOVE.L CA12,-4CA1,D1.W) ¿add 2nd pt to the end of list Ө 1MOVE.W WHERE*2C(A52,01 ¿delta X 
Spacca  TST.W (AD ;Check if short or long point SUB.W LastClick_W+2(A5),D1 
BMI.S 00 BPL.S e2 ; ABS 
MOVE.L (А1)+, (Аб )+ ;nothing to unpack NEG.W 01 
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@2ADD.W 00,01 ;0х+0у 
CMP.W 83,01 ¿allow for а 3 pix max distance 
BGT.S 00 
ST DoubleClick(CA5) ;уеѕ, it’s a double click 


@QMOVE .L WHENCAS),LastClick_T(A5);Record time and.. 
MOVE.L WHERECAS),LastClick_WCA5) ; location 


RTS 

ActMenu BSR  param0nStack ; load the stack 
-EnableItem ;3 items 
-EnebleItem ¿to enable 
-EnebleItem 
-DrewMenuBar 
RTS 

DimMenu BSR  param0nStack ;load the stack 
-DisebleItem 13 items 
-DisebleItem ;to disable 
-DisableItem 
_DrawMenuBar 
RTS 

paramonS tack 


MOVE.L СЅР )+, Аб 


;RTS in AQ 


MOVE.L ЕаіНатасА5 ), -CSP) 


MOVE.W #1, -CSP) 


¿undo 


MOVE.L EditHand(A5),-(SP) 


MOVE.W #3,-($Р) 


MOVE.L EditHand(A5),-(SP) 


MOVE.W #5,-(SP) 
JMP (АЙ) 


MakePoly 


Shor tComment PolyBegin ,Here starts our special Poly 
Shor tComment PicPlyClo ;always a closed Poly in our case 


TST.W LiscioCA5) 
BEQ.S @1 


15 our poly to be smoothed? 
;branch if not 


MOVE.L CommentHand(A5),A1 ;Handle to smooth verbs 


MOVE.L СА1), Ад 


,deference 


MOVEQ *Frame+Close, 00 assume only closed and framed 


TST.W CurPat(A5) 

BEQ.S 80 

ADDQ.W 8Ғ111,00 
e2MOVE.B DØ, CAB) 


218 our poly filled ? 


,add fill verb 
¿Set verb = Close*Freme*CF ill) 


LongComment PolySmooth, 1,А1 ;smooth flag true 


MOVE.L TempRgn(A5),-(SP)  ;seve clip 


-GetClip 


PEA ZeroRect(PC) ;if not aware of comments then no print 


-ClipRect 


BSR — DrewPoly;Pess laser original vertexes to be smoothed 
MOVE.L TempRgn(A5), -CSP) 


-SetClip 


;а11он others to print 


ShortComment PolyIgnore X ;ignore following poly if laser 


e 1BSR ReDraw 


j;Simulate spline for non-laser printers 


Shor tComment PolyEnd jEnd special poly 


RTS 


InitGlobals 
CLR.W CurPat(A5) 


;No fill pat 


MOVE.L *$10001,CurPen(A5) ;PenSize 1,1 
MOVE.W *12,CurScale(A5)  ;72 dpi 


MOVE.W * 1, ChkPatCA5) 


¿first pat checked 


MOVE.W #1, ChkscaleCA5) 312 dpi checked 


RTS 
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InitMac 
PEA -4(A5) 
_InitGraf 
_InitFonts 
_InitWindows 


;Recite Mac pray 
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_InitMenus 

СЕВ. -CSP) 
-InitDialogs 
_TEInit 

-InitCursor 

MOVE.L #$0000ЕЕЕЕ ‚00 
-FlushEvents 

RTS 


SetWindow 
MOVE.L (АБ), Аб 


; No restart procedure 


; Flush 811 events 


¿Pointer to QuickDraw Globals 


LEA — screenBitsCAQ0,AQ  ;Ptr to Bounds of Screen В1 {Мар 
MOVE.L 6СА0),МКес((А5) бес & set Screen Rect 
MOVE.L 10CA0), WRect+4(A5) 


PEA — WRect(A5) 


MOVE.L *t$100010,-CSP) ,allow 16 Pixels inside 


-InsetRect 


MOVE.L WRectCA5), WBounds(A5) 


MOVE.L WRect*4CA5), WBounds*4CA5) 


MOVE.L *$400080,WSize(A5) ;Grow Rect (64, 128,768,768) 


MOVE.L  %$3000300,WSize+4(A5) 


MOVE.W MBarHe ight, Dd 
ADDI.W 818,00 
ADD.W DO, WRectCA5) 


CLR.L -(SP) 
CLR.L -CSP) 

PEA — WRect(A5) 
РЕА ‘Polygon’ 
MOVE .B 8-1,-(5Р) 
MOVE .W 88,-(5Р) 
MOVE.L $-1,-CSP) 
CLR.B -CSP) 
CLR.L -CSP) 
-NewWindow 


;according to PageSetUp 
;Center WRect on video 
‚Те bar 

jsubtract Menu Height 


¿Create our window 


; document :Polygon 


¿has zoom box 


MOVE.L (SP),TheWind(A5) ; leave it on stack and save 


-SetPort 

BSR CalcGrow 
BSR ClipWind 
BSR PutGrow 
RTS 


Se tMenus 


MOVEM.L A3/D3-D5, - CSP) ¿save stuff 


LEA — MenuHndListCA5), АЗ 


MOVEQ #1,D3 
MOVEQ #4-1,04 
MOVEQ 80/05 

BSR PushMenus 


¿Start with Menu 1 

4 menus (-1 for DBRA) 
¿before ID = 0 
¿sequential ordering 


MOVE.L MelaHand(A5), -(SP) 


MOVE.L € ^DRVR^,-CSP) 
~AddResMenu 


MOVEQ %°A’,D3 
MOVEQ #2,04 
MOVEQ #- 1,05 
BSR PushMenus 


;уеѕ, we support DA 
¿add submenus 

¿Start with Menu 65 
¿through menu 67 
¿hierarchical beforeID 


CheckItm PenHand, 1 ;check items 
CheckItm FpatHend, # 1 
CheckItm PscaleHand,? 1 


-DrawMenuBar 


MOVEM.L CSP )+,A3/D3-D5 ,restore stuff 


RTS 


PushMenus 
CLR.L -CSP) 
MOVE .W 03,-(ӨР) 
_GetRMenu 
MOVE.L CSP), САЗ )+ 


10 of Menu to get 


¿Save Hndl trusting global ordering 


; Init Draging bounds Rect 


(42 should calc this rect 


;Stuff with MHandles from here on 
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MOVE .W D5, -CSP) ;Hndl was left on stack * beforeID 
_Inser tMenu 

ADDQ.W 81,03 ¿Next ID 

DBRA  D4,PushMenus 

RTS 


GetHandles 
MOVE.L 't$7FFF,D0 ;ask for 32K 
-NewHandle 
BNE — Error 
MOVE.L A0,PolyHand 


MOVE.L "$FFFE,DO ¿ask for 64K 
-NewHandle 

BNE Error 

MOVE.L A®,PolyBuf ferCA5 ) 


MOVEQ 8120,00 ;Print Record Size 
-NewHandle 

MOVE.L A®,PrintRecCA5) 

MOVE.L A9,-CSP) 

prExec Pr intDefault Fill it with defaults 


MOVEQ 88,00 ¿enough for any comment data 
-NewHandle 

BNE Error 

MOVE.L Аб, CommentHand(A5) 


CLR.L -CSP) ;our fill region 
-NewRgn 
MOVE.L (SP)+,RgnHand(A5) 


CLR.L -CSP) 

-NewRgn 

MOVE.L CSP)+, TempRgn(A5) ;А dummy region 
RTS 


ERROR BSR Bippa ¿WARNING (62 
BSR Bippa ;Best Error Handler routine ever written 


BSR Bippa ;but I know you could do even better 
-ExitToShe1]1 


Bippa MOVE.W 83,-(ӨР) 
-SysBeep 
RTS 


OroCurs CLR.L -(SP) ¿watch cursor 
MOVE .W #4, -CSP) 
-GetCursor 
MOVE.L CSP2*,A0 
MOVE.L CA0),-CSP) 
-SetCursor 
RTS 


ZeroRect DC.W 90,0,0,0 


7 


; ——— —— GLOBALS 

7 

WRect DS.B 8 ¿Window stuff 
GrowBox 05.8 8 

WBounds DS.B 8 

WSize 05.8 8 

TheWind DS.L 1 

WINDOW DS.L 1 


MenuHndL ist DS.L ‚до not change this ordering! 


0 
Ме] аНапд DS.L 1 ¿Menu Handles 
FileHand DS.L 1 
Edi tHand DS.L 1 
DoHand DS.L 1 
PenHand DS.L 1 ;Hiererchical Menu Handles 
FpatHand DS.L 1 
1 


PscaleHand DS.L 
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EVENTRECORD 05.8 0 ‚Му event. 
WHAT DS.W 1 
MESSAGE 01.1 
WHEN DS.L 1 
WHERE DS.L 1 
MODIFY DS.W 1 
MENU DS.L 1 ;Other.. 
PolyBuffer DS.L 1 
PolyDrawn DS.W 1 
whileDrawing DS.W 1 
NumPoints DS.W 1 
BytesWritten DSW 1 
LastPoint 051 1 
CurPoint DS.L 1 
OldPoint DS.L 1 
MousLoc DS.L 1 
LastClick. T DS.L 1 
LastClick_W DS.L 1 
DoubleClick DS.W 1 
CurPat 0$. 1 
CurPen DS.L 1 
CurScale DS.W 1 
ChkPat DS.W 1 
Chkscale DS.W 1 
Liscio DSW 1 
RgnHand DS.L 1 
TempRgn DS.L 1 
CommentHand DS.L 1 
DskName 05.8 64 
ЗауеРог{ 051 1 
PrintPort DS.L 1 
PrintRec DS.L 1 
PrStatus DS.B 26 
ItmHit 05.4 1 


Listing: Smooth.R 


* Resources for Smoother 


* (Make sure blank lines don’t have space characters in them!) 


SmoothRes .Ке] 
APPLDEMO 


TYPE DEMO - GNRL 


ІР 
v 1.0 by Raul Tabasso - Roma 22/6/88 


TYPE FREF 
, 128 
APPL 0 


TYPE BNDL 
, 128 

DEMO 0 

ICNS 

0 128 

ҒКЕР 

0 128 


ТҮРЕ ICN# = GNRL 
2; Appl Icon 
, 128 

.H 
0000 0000 0000 0000 0000 0000 0000 3FCO 
0001 С030 0002 0008 0004 0004 0004 0002 
0008 0002 0008 0002 0008 0182 0008 0204 
0004 0208 0002 01ІҒ0 0001 0000 0000 8000 
0000 6000 0000 1800 0000 0700 0000 00С0 
0000 0030 0000 000С 0000 0004 0000 0002 
0000 0002 0000 0002 0000 0002 0000 0004 
0000 0004 0000 0008 0000 0030 IFFF FFCO 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
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FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
| —— asas 


* — MENUS 


TYPE MENU 

,1;,Apple menu 
MA ;,Mpple char 
About Smoother.. 
(- 


TYPE MENU 


2 
File ;;File menu 
New polygon/N 
Page Setup.. 
(Pr int... 
Laser pen scaling/\1B!C 
; Submenu 67 
Quit/Q 


TYPE MENU 
n 
Edit  ;;Edit menu 


Copy/C 
Paste/V 


TYPE MENU 


‚4 
Options 
(Smooth/S 
Pen size/\1B!A ;;submenu 65 
Fill tone/MB!B ;;and 66 


;,Polyggon menu 


TYPE MENU 


Psize ;; Pen Size submenu 


TYPE MENU 
‚66 
Fpet ;; Fill Pattern submenu 
№ fill^1 
25572 
50% “3 
158^4 
Black^5 


TYPE MENU 
‚67 
PScale 
12 dpi 
150 dpi 
. 300 dpi 
600 dpi 
1200 dpi 


;; Pen Scaling submenu 


TYPE DLOG 
, 206 ;; ID 
The about dialog 
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80 80 220 400 ;; Rect 
Visible NoGoAway 

1  ;,proc ID 

Ø ;;ref con 

256 ;;DITL related 


TYPE DITL 
, 296 


Button 
100 200 120 256 
OK 


StaticText 
32 64 80 256 
Smoother by Raul Tabasso. ++ 


Ап exemple program on polggon's comments 


NE 
x — Icons for submenu n° 66 ——— 


TYPE ICON = GNRL 
,251 

H 

FFFF FFFF FFFF FFFF (000 0003 COO 0003 
(000 0003 С000 0003 (000 0003 С000 0003 
(000 0003 (000 0003 (000 0003 (082 3С03 
(0С2 6603 COE2 6603 (0-2 6603 СОВА 6603 
CO9E 6603 СОВЕ 6603 (086 6603 С082 3С03 
(000 0003 С000 0003 (000 0003 С000 0003 
(000 0003 С000 0003 (000 0003 С000 0003 
(000 0003 С000 0003 FFFF FFFF FFFF FFFF 


ТУРЕ ICON = GNRL 
‚258 

H 

FFFF FFFF FFFF FFFF E222 2223 С000 0003 
C888 8888 С000 0003 E222 2223 С000 0003 
C888 8888 С000 0003 E222 2223 С000 0003 
C888 8888 С000 0003 E222 2223 С000 0003 
(888 8888 (000 0003 E222 2223 С000 0003 
(888 8888 (000 0003 E222 2223 С000 0003 
(888 8888 (000 0003 E222 2223 С000 0003 
C888 8888 (000 0003 FFFF FFFF FFFF FFFF 


TYPE ICON = GNRL 

„Н 

FFFF FFFF FFFF FFFF ЕААА АААВ 0555 5557 
ЕААА АААВ 0555 5557 ЕААА АААВ 0555 5557 
БАЛА AAAB 0555 5557 ЕААА АААВ 0555 5557 
ЕААА АААВ 0555 5557 ЕААА АААВ 0555 5557 
EAAA AAAB 0555 5557 ЕААА АААВ 0555 5557 
ЕААА АААВ 0555 5557 ЕААА АААВ 0555 5557 
БАЛА AAAB 0555 5557 EAAA АААВ 0555 5557 
БАЛА АААВ 0555 5557 FFFF FFFF FFFF FFFF 


ТҮРЕ ICON = GNRL 

н’ 

FFFF FFFF FFFF ҒҒҒҒ 0000 DDDF F777 7777 
0000 DDDF F777 7777 0000 DDOF F777 7777 
0000 DDDF F777 7777 0000 DODF F777 7777 
0000 DDOF F777 7777 DDOD DOOF F777 7777 
0000 DDOF F777 7777 0000 DDDF ЕТТТ 7777 
0000 DDDF F777 7777 0000 000Е F777 TTTT 
0000 DDOF F777 7777 DDOD 000Е F777 7777 
0000 DDDF F777 7777 FFFF FFFF FFFF FFFF 


TYPE ICON = GNRL 


,261 


„Н 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 


FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 


к 
х — Icons for submenu n9 65 ——— 


TYPE ICON - GNRL 
‚ 261 

.H 

0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 FFFF FFFC 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 


ТҮРЕ ICON = GNRL 

‚268 
H 
| 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 FFFF FFFC FFFF FFFC 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 


TYPE ICON = GNRL 
,269 

‚Н 

0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 FFFF FFFC FFFF FFFC FFFF FFFC 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 


ТҮРЕ ICON = GNRL 
‚210 

.H 

0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
FFFF FFFC FFFF FFFC FFFF FFFC FFFF FFFC 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 


TYPE ICON = GNRL 
‚271 

H 

0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 ҒЕҒЕ FFFC 
FFFF FFFC FFFF FFFC FFFF FFFC FFFF FFFC 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 


e | 


гыгы?» 
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Breaking the Four Window Barrier C MacTutor Vol. 4 No. 1 
| {уре а, 
It seems that every good Macintosh example program (of a type. b, 
texteditor, graphics program, or whatever) is hung up on the idea type_c 
of four windows. Of course, those that aren’t such good example : 
programs only use one window! This limit always seems to be a typedef union 
result of the unnecessary use of global data structures. Í св 
Most multi-window Macintosh example programs contain P. 
some lines that look like: F /* tupe-a window data */ 
8; 
WindowPtr some windowsthow. many]; et 
data structure some.data[how. mang]; T /* type_b window data */ 
b; 
where how. many is defined to be four. The programmer will struct 
claim that it is easy to change this number to be as large as ( 


necessary, and the application can be easily recompiled. That is /* type-c window date */ 


fine for the programmer, but what about the end user. He is stuck ) UE *content. ptr, **content. hnd; 
with whatever number the programmer happens to choose. If the 
programmer happens to choose a number of windows and data 
structures that perfectly fits a 512K Macintosh, then the user is enum window type xxx; — /* optional, appl. specific */ 
probably not able to take advantage of the extra memory of a content-hnd! yyy; — /* could include union directly */ 
Macintosh Plus, much less a Macintosh with even more memory. ) window deta, *data ptr, **data hndl; 

In actuality, it is not necessary to predefine any number of 
windows, or the data structures that are associated with them. 
Since the Macintosh hasan operating system thatknows all about 


bs ded struct 


make_window( type) 


windows and how to keep track of them, it makes little sense for ni window type type; 
lication pr r i is eff 
the app ication programmer to duplicate this е ort. ы К 
The window data structure contains а 32-bit field called date hndl a. data; 
refCon which Inside Macintosh describes as “the window's content hndl a. content; 


reference value field, which the application may store into and 


access for any purpose". One such purpose, which is mentioned ао 


but not demonstrated іп many books on Macintosh program- (WindowRecord *)NewWindow(...); 
ming, is to store a handle to some application specific data oor. | 
А 5 š ; : : (data_hnd1] )NewHand 1 eC fC )); 
structure which contains the information that is pertinent to that a_conten t 221... і 
window. (sizeof Ccontent)); 
Since every event given to an application by the Event ("ra data).xxx = type; 


(**a_data).yyy = a-content; 


Manager will contain а pointer to the window concerned, there a_window->refCon = (long?a data; 


isno need forthe application to keep an array of WindowPtrs; and 
since each window contains a refCon field, there is no need to ) 
keep an array of data structures. Instead, allocate the necessary 
space for the data structure at the time the new window is created, 


and put its handle in the refCon field of the window's data шаа, 
structure. Then, whenever an event is processed, just pass the EventRecord the.event; 
WindowPtr along to the functions which are going to process the WindowPtr which.window; 
event. These functions then can get access to the data structure Да ыы 
when they need it. ni 
The code fragments which follow demonstrate the concepts while (TRUE) 
described: 


| if CGetNextEventCeveryEvent, 
diu window. type &the event?) 
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( 
š G (the_event.what) 


case mouseDown: 
window-code = FindWindow 


(the_event.where, 


&wh ich_window); 
switch (window. code) 


case inSysWindow: 

SystemC] ickC&the event, 
which. window); 

break ; 


case inContent: 


process_window(which_window); 


break; 


break; 


process_w indow( the_window) 
WindowRecord *the_window; 


( 
data.hndl the_data; 
the_data = 
(data. hndl2Cthe. window-?ref Con); 
me (Сх the. dete). xxx) 
case іуре. 8: 


process. а. windowCthe. window); 
break; 
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case type. b: 
process. b. windowCthe. window); 
break; 


case type.c: 
process. c windowCthe window); 
break; 


This general technique may, in some very particular cases, 
slow things down a little. Generally, this won't be the case 
because most applications spend a majority of their time process- 
ing NULL events. If you wanted to speed things up a little bitand 
still maintain the dynamic allocation capabilities of this program- 
ming approach, use just one globally declared WindowPtr and 
one data handle and just update them to always point at the 
window/data structure that the current event refers to. Then you 
wouldn't have to pass the event’s WindowPtr to the called 
function(s). 

Of course, most applications need to be able to find all of 
their windows at times, e.g., when Quitting the application so that 
changes can be saved, or when updating the windows. At those 
times, it is still possible to avoid using a global array merely by 
calling Front Window0 and following the linked list of pointers 
stored in the nextWindow field of the window’s data structure. 

This approach to creating windows in an application, which 
I call “fire and forget" (and which could be considered as a small 
first step towards object oriented programming), will allow your 
application to create as many new windows (and their associated 
data structures) as the user desires. It is also a convenient way of 
manipulating different types of windows in a single application. 
(Itis very easy, forexample, to imagine MacDraw and MacWrite 
in a single application!) Of course, your application has to check 
available memory each time it tries to create a new window/data 
structure to make sure there is enough available, but that is a small 
price to pay for the increased utility the user can get from having 
a program that "grows" with his hardware. | 

cios 
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Postscript Programming 
Overview & Downloader in C 


In this article, I’m going to presenta programmer's overview 
of PostScript. This overview includes comparisons between 
PostScript and QuickDraw, information about using the stack 
and a brief explanation of the LaserWriter driver. At the end of 
the article, I'll present the PAP manager calls (which allow direct 
access to the LaserWriter over AppleTalk) and C source code for 
a PostScript downloader. 


Overview of PostScript 

PostScript is a graphics language that’s designed to set type 
and graphics on high-resolution devices such as laser printers and 
typesetting machines. In most of its implementations it runs on 
a dedicated processor that’s contained in or connected to a 
printer. Though these printers vary considerably in their capabili- 
ties, PostScript is device-independent, so programs written for 
one PostScript device will usually run on another. 

In addition to its graphic capabilities, PostScript contains a 
full complement of standard language features (floating point 
arithmetic, string and array manipulation, etc.) and could con- 
ceivably be used for non-graphics applications. It most closely 
resembles FORTH in its syntax and overall “feel” (but, thank- 
fully, PostScript carries no social stigma). However, most 
FORTH systems provide the option of controlling the processor 
at a very low level and PostScript (because it is device-independ- 
ent) allows only high-level programming. 

PostScript’s design shows the influence of SmallTalk. 
Though it isn’t really object-oriented (there is no messaging 
system and no inheritance), the documentation describes in- 
stances of the data types as “objects,” and the interpreter per- 
forms comprehensive type checking. The influence of SmallTalk 
can probably be traced to PARC, where PostScript’s principal 
designer, John Warnock, worked during the late 70’s and early 
80’s. Since SmallTalk and QuickDraw share common ground, 
Mac programmers will recognize some PostScript commands. 


Terminology 

In the PostScript documentation, the built-in commands are 
usually referred to as operators. In this article, they will be 
referred to in a number of more familiar ways, such as routines, 
procedures, functions, etc. The name used doesn’t provide any 
additional information about the operator: an operator referred to 
as a function won’t necessarily return a value. The data used by 
operators are technically called operands, but I often use argu- 
ments and parameters instead. It’s good to use the correct 
PostScript terminology, but unfamiliar terms can make a new 
language seem even more foreign. 


PostScript and QuickDraw 


© The Definitive MacTutor, Vol. 4 


Nicholas Pavkovic 


Perimeter 
Chicago, IL 
MacTutor Vol. 1 №. 1 


To give you a better sense of PostScript’s capabilities, Га 
like to cover some of the similarities and differences between 
PostScript and QuickDraw. While reading this section, think of 
the PostScript function calls as Pascal or C calls in which the 
arguments precede the routine names. Note that the PostScript 
interpreter is case-sensitive and all of the built-in commands аге 
written with lowercase letters. 


Coordinates, Navigation and the Path 

Unlike QuickDraw, PostScript uses a Cartesian coordinate 
system with the origin located in the lower left hand corner of the 
page. The x coordinates increase from left to right and the y 
coordinates increase from bottom to top. In this coordinate 
system, the basic unit is the point which is 1/72” wide (the width 
of a pixel on the Macintosh screen). Since PostScript supports 
floating point, coordinates don’t have to be integers. 

Like QuickDraw, PostScript uses a pen and positions it with 
the moveto command. Since the arguments precede the routine, 
the code to move the pen to position (72, 18) would read 72 18 
moveto. To move the pen relative to its current position, use 
rmoveto. Straight line segments are drawn using lineto and 
rlineto. These commands are preceded by an x and y coordinate 
(or offset, if relative movement is involved). 

Unlike QuickDraw, line segments are not drawn on the page 
as the commands are executed. The segments are accumulated 
into the current path, a hidden data structure that keeps track of 
the lines drawn on the page. Once you’ ve created а path, you can 
draw (outline) it using the stroke operator or fill its interior using 
the fill operator (neither operator takes any arguments). The 
nature of the fill or the outline depend on the pen’s characteristics 
when fill or stroke is called. The PostScript pen’s state differs 
somewhat from the QuickDraw pen. The PostScript pen does not 
have a transfer mode; whatever you draw will cover anything 
printed underneath it. And though the PostScript pen can be set 
up to draw with a pattern, it’s a somewhat tricky procedure. 
Usually you'll use the PostScript operator Setgray, which allows 
you to fill the path with different levels of gray. setgray is 
preceded by the gray level, a decimal that ranges from 0 (black) 
to 1 (white). 

PostScript’s setlinewidth is the PostScript version of 
QuickDraw’s PenSize routine; it’s preceded by the desired line 
weight (vertical width), which can be fractional. This command 
doesn’t alter the horizontal width of the pen. 0 setlinewidth 
generates the thinnest line available on the PostScript device 
you’re using. Lines are drawn from the center; half of the line’s 
weight is above the segment specified and half is below. 

fill and stroke have one surprising side-effect: they erase the 
Current path and make the current pen position indefinite. Be- 
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cause the pen position is indefinite, you'll need а moveto to 
position the pen after you've used one of these operators. The 
erasure of the current path causes problems if you want to create 
a figure that's both stroked and filled. To do so, you must either 
draw the object twice (fill it once and stroke it the second time) 
or use the commands gsave and grestore. These commands 
save and restore the graphics state, which includes the current 
path and pen state (among other things). gsave fill grestore 
stroke fills and strokes the current path. 

Once you've finished drawing and you want to see your 
creation, execute showpage. Up to this point, all drawing has 
been done on a bit image of the page that exists only in memory. 
showpage transfers the memory image to the physical page and 
ejects the page. 


Setting Text 
Before уоц сап draw апу text, you must indicate the font that 


you wish to use. The commands needed to set the font to 18 point 
Times-Roman are: 


/Times-Roman f indfont 
12 scalefont 
setfont 


It's a little too early to explain exactly why this works, but 
I will point out that findfont can be preceded by any valid font 
name (beginning with a backslash) and scalefont is preceded by 
the desired font size. If you don't know the correct spellings of 
the font names, you can find them by executing FontDirectory 
pop - forall, another piece of code that will have to remain 
unexplained. Note that PostScript uses a different name for each 
font style, and certain standard Macintosh styles (Outline, 
Shadow and Underline) aren't standard on the LaserWriter. 

After you've set the font, you'll need to move into position 
with moveto. Then use show to draw the text. show is preceded 
by the text to be drawn, enclosed in parentheses, as in (Hello, 
world) show. The current gray level will be used to draw the text. 


Coordinate Transformations 

Before being drawn, every coordinate is transformed by the 
current transformation matrix or CTM. To modify the drawing 
space, you can adjust the СТМ directly with some general matrix 
operators, or you can avoid the linear algebra and use the 
following “convenience” operators: 


x y scale Scales the drawing space 
Default: 1 1 scale 
rotate Rotates the axes 
x y translate Translates the origin to the point (х,у) 


Note that these operators affect drawing that is done after 
they are invoked; they don’t affect any text or graphics that have 
already been drawn. 
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What's Missing? 

There are a few features that QuickDraw programmers will 
miss in PostScript. 

As mentioned above, there are no transfer modes; you'll 
have to be careful about the order in which objects are drawn and 
make use of PostScript's clip operator. 

Though PostScript's text processing is more sophisticated 
than QuickDraw's, PostScript contains no operators for wrap- 
ping text (there's no TextBox equivalent). You can write a 
simple line-breaking procedure in PostScript, but for reasons of 
speed you'll probably want to do any heavy-duty hyphenation 
and justification on the Mac's processor. 

Regions are missing from PostScript, as are most of 
QuickDraw's routines for drawing geometric shapes. In both 
cases, it's not difficult to program functional equivalents. 


Visuallzing the Stack 

Like FORTH, PostScriptis a stack-based language. FORTH 
programmers will find their experience with FORTH's stack 
very useful when learning to use PostScript. 

Assembly language programmers will also benefit from 
their familiarity with the stack. The stack preparation required by 
PostScript procedures is conceptually similar to the setup that 
occurs in assembler prior calling a Pascal function or on entry to 
a definition routine that follows the Pascal calling conventions. 
In most respects, however, PostScript and assembler are quite 
different. The PostScript stack is "intelligent" in the sense that it 
keeps track of its elements’ types and sizes. PostScript relies on 
it for arithmetic operations that assembler normally handles with 
registers, and PostScript provides a full set of methods for 
changing the order of elements on the stack. One thing that 
PostScript doesn't use its operand stack for is return addresses, 
So you don't have to worry about accidently branching into a data 
structure if your calls aren't set up correctly. 

For programmers used to high-level languages, the stack 
will seem somewhat cumbersome at first. For example, subtract- 
ing 5 from 7 is accomplished with the code 7 5 sub. [If you 
remember the great HP 65 calculator and it's reverse polish 
notation, then this will appeal to you. -Ed] As each number is 
read, it's pushed onto the top of the stack. The prior contents of 
the stack are moved downwards. Keeping in mind that PostScript 
is interpreting the statement from left to right, consider the 
following visual representation of what happens: 

AS you can see, the sum is pushed onto the stack after the 


7 5 sub 


addends are remo 
want the result to appear on your screen, type - after the code. - 
pops the result off the top of the stack and echoes it to the output 
device (it ends up on your screen). 
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The way that the stack is used may remind you of a RPN 
calculator. An associate of mine who is studying PostScript 
prefers to think of the stack in terms of shifting blocks. He's cut 
a large piece of erasable whiteboard into rectangular sections, 
and he emulates the stack by writing values onto them and 
shifting their positions. You may not need to go this far to acquire 
proficiency with the stack, but you will need to retain a mental 
image of the stack while you're coding. Since many of the simple 
operators in PostScript don't do much to the stack, it's tempting 
to look at them simply as functions preceded by their arguments 
and forget that the stack exists. Unfortunately, this approach 
won't get you far when you're trying to understand PostScript's 
stack manipulation operators. 

dup duplicates the stack's top element: 


5 dup 


exch reverses the order of the top two elements: 


7 5 exch 


roll rotates the order of elements on the stack. It's often used 
to move the bottommost element to the top of the stack: 


(before) (after) 


top of stack 


roll takes two integer arguments. The first argument deter- 
mines the number of elements that are affected by the rotation. 
The second argument specifies how many rotations occur and the 
direction of these rotations. A negative integer will move ele- 
ments from the bottom of the stack to the top and a positive 
integer will move elements from the top of the stack to the 
bottom. The code necessary to accomplish the above rotation 
would read 3 -1 roll. Threeelements are affected by the operation 
(if there are any elements beneath the third element, they'll 
remain in place). The -1 causes the elements to rotate once, 
moving the third element to the top of the stack. If -2 had been the 
second argument, 9 would have been moved to the top of the 
stack first and 8 would have been moved to the top of the stack 
next. 
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Obviously, rolls can get quite complex. It's frustratingly 
similar to Rubik's cube: though it's easy to get a particular 
elementinto place, all the other elements get moved around in the 
process. To help keep track of the stack, most programmers rely 
on a standard notation that looks like this: 


abc—bc 


The letters denote elements on the stack. The ones placed 
before the dash represent the state of the stack before an operation 
and those following the dash represent the stack state after the 
operation. The letter farthest to the right represents the element 
that's on top of the stack. exch's effect on the stack might be 
described by a b — b a. For some operations, you may want to 
use descriptive names instead of letters. The stack effects of add 
could be written addend1 addend2 — sum. The PostScript 
Language Reference Manual's reference section describes each 
PostScript operator using a variant of this notation. add, for 
example, contains the description num1 num2 add sum. The 
dash has been replaced with the name of the operator. A short 
dash is used to represent an empty stack, as in - Stroke -. Stroke 
takes nothing from the stack and leaves nothing on the stack after 
execution. 

The stack notation can be used to describe the effect of a 
single instruction or it can summarize the effect of numerous 
operations. If I'm writing a tricky program (or debugging code 
that I had believed to be simple), I'll sometimes use the notation 
to describe the state of the stack before and after the execution of 
each line. 


Declarations, Types and Dictionaries 

Many conventional languages require you to declare a 
variable's name and type before it can be used. In PostScript, an 
assignment statement serves as the declaration. The variable's 
type is determined by the value you assign to it. For instance, / 
counter 1 def defines an integer variable named “counter” and 
assigns it the value 1. 

In addition to integers, you can assign floating point values 
(by including decimals), strings (using parentheses as delimiters 
instead of quotation marks) and arrays (bracketing the elements 
with ‘Į’ and 47). Arrays can be heterogeneous — the firstelement 
might bean integer, the seconda floating point value and the third 
a string. This allows the implementation of complex data struc- 
tures, though you'll rarely need them. 

Let's examine the variable definition a little more closely. 
The first token, /Counter, consists of the variable name counter 
preceded by a backslash. When PostScript normally encounters 
a variable name, it pushes the variable's value onto the stack. In 
this case, however, the backslash indicates that the identifier is to 
be treated as a name (technically a literal name) and pushed onto 
the stack as such. After placing /Counter on the stack, 1 is placed 
on top of it and the PostScript operator def is invoked. def 
transforms /counter into a usable variable. First, it checks 
PostScript's symbol table to see if the named variable already 
exists. PostScript stores its symbols and their values in a data 
structure called a dictionary. If def can't find the variable name 
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іп the dictionary, it creates an entry in the dictionary using the 
supplied name, allocates memory for the data and makes the 
necessary assignment. À variable can be used in expressions as 
Soon as it's been defined. 

The code /counter counter 1 add def increments the 
counter. counter 1 add pushes counter's value onto the stack 
and adds one to it, placing the result оп the stack. The surrounding 
code, /counter def is the same as it was in the original 
declaration. When def is executed, though, it discovers that a 
variable named counter already exists and simply assigns the 
new value to it. 

def is also used to define procedures. The syntax is the same, 
except that the body of a procedure is used instead of a variable 
value. The body consists of PostScript operators (and their 
arguments) enclosed by curly brackets. When PostScript is 
interpreting a program and finds thata name refers to a previously 
defined procedure, the bracketed instructions are executed. 

Until now, we've been speaking of a single dictionary for 
variable and procedure names. PostScript actually uses multiple 
dictionaries when searching for an identifier. It searches through 
alist of dictionaries consecutively until the symbol is found or the 
last dictionary is searched. The order in which the dictionaries аге 
searched is determined by the dictionary stack. Normally, the 
dictionary on the top of this stack is the userdict, and (since it's 
first in the list) this dictionary holds the variables and procedures 
created with def. The systemdict dictionary is underneath 
userdict on the dictionary stack, and it contains the built-in 
PostScript operators and the system's global variables. There are 
afew characteristics of PostScript's dictionaries to keep in mind: 


е Because of the order of the dictionaries, it's possible to 
override a built-in operator in systemdict by defining 
one with an identical name in userdict. 

° Symbols in userdict only remain there for the duration 
of the job. А program cannot use variables or proce- 
dures defined during an earlier download. 

е Symbols in userdict are global. There's no way of 
allocating private local variables and then de-allocating 
them at the end of a procedure. 

е There'sno way to remove entries from userdict during 
the execution of a job. 

° userdict cannot store an unlimited number of entries. 


Efficiency-concious programmers may be tempted to put 
everything on the stack and move the values into place as needed 
using the stack operators. This approach will certainly avoid the 
dictionary overhead, but the code necessary to do this is ex- 
tremely difficult to write and debug, and the efficiency benefits 
are often imperceptible. If you don't define variables recklessly, 
you're not likely to hit userdict's limit (around 200 symbols), and 
the speed overhead incurred by adding a symbol to the dictionary 
is minor when compared to the amount of time the LaserWriter 
takes to place marks on the page. 


PostScript in Perspective 
To provide a point of reference for programmers accus- 
tomed to conventional languages, I'd like to compare the follow- 
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ing C function, CenterString, to a similar PostScript function. 
The C version takes a point, a length and a string pointer as 
arguments. It draws the string so that it is centered on the interval 
[point.h, point.h--length] at the height point.v. The PostScript 
version does much the same thing, drawing on the page instead 
of the screen. Each line of the PostScript code contains a 
comment (delimited by a 96) that details its effect on the stack. 


CenterString( StertingPoint, CenterLength, StringPtr ) 
PointStartingPoint; 

intCenterLength; 

ез *StringPtr; /* А Pascal String */ 


int Width; 

Width - StringWidthC StringPtr 2; 

StartingPoint.h = StartingPoint.h + 
(CenterLength - Width2/2; 

MoveToC StartingPoint.h, StartingPoint.v 2; 

DrawStringC StringPtr 2; 


Once again, in PostScript: 


/CenterString Я x y clen str - 


dup $xyclen str - x y clen str str 

stringwidth % x y clen str str - x y clen str stringx stringy 
pop $ x y clen str stringx stringy – x y clen str stringx 
3 -1roll$ x y clen str stringx - x y str stringx clen 

exch $xystr stringx clen - xy str clen stringx 

sub % x y str clen stringx - x y str clen-stringx 

2 div $ x y str clen stringx - x y str (clen-stringx)/2 


Я offset = clen-stringx/2 
4 -1roll$ x y str offset – y str offset x 
add $ y str offset x — y str offset+x 
3 -1 roll$ y str Coffset*x) - str Coffsettx) U 


moveto Я str Coffset+x) y - str 
show $str-- 
) def 


Before we examine the PostScript version, let me point out 
that it's designed to show off some of the stack operators. After 
you've read through its explanation, I'll present a different 
version that's less stack-intensive. 

Mostof the code in CenterString is devoted to arranging the 
stack so that everything is in order for the mathematical opera- 
tors. Since we need to reference the string twice in this procedure 
(once to measure it and once to draw it), dup is used to make a 
copy of the string. Actually, dup doesn’t copy the string; rather, 
it copies a reference (pointer?) to the string. The next operator, 
stringwidth, differs somewhat from its QuickDraw relative: the 
PostScript version returns both a horizontal and a vertical size 
(just in case you’re working with a non-Western font that’s 
written from top to bottom). We don’t need the vertical compo- 
nent, so we pop it off the stack. Next, we use roll to move Clen to 
the top of the stack. After an exch, the two elements on the top 
of the stack are in the correct order for the subtraction. Sub leaves 
the difference between the centering length and the string’s width 
on the top of the stack. To compute the x coordinate of the 
centering point, we need to halve this difference (2 div) and add 
the quotient to the x coordinate of the starting point. Since the x 
coordinate of the starting point is on the bottom of the stack and 
the stack is 4 elements deep, we use 4 -1 roll to move it to the top 
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and add the offset to it. Now that the new x coordinate has been 
determined, we need to move the y coordinate to the top stack, so 
that the stack will be in order for moveto. The stack is now 3 
elements deep and the starting point's y coordinate is on the 
bottom, so we use 3 -1 roll to bring it to the top of the stack. 
moveto moves the pen to the x and y coordinates that are on top 
of the stack, and show draws the string, which is the only 
remaining element on the stack. 

The following version of CenterString avoids most of the 
stack reorganization described above. On entry, this routine 
removes the parameters from the stack and places them into 
global variables: 


оа % ху clen str - 


/str ехсһ def $ ху clen str - x y clen 

/clen exch def Sxycln-xy 

/уроз exch def $ x 

/xpos exch def $ x 

clen $ --clen 

str stringwidth pop 8 clen - clen stringx 

sub $ clen stringx - clen-stringx 

2 div $ clen-stringx - (clen-stringx)/2 
xpos add $ (clen-stringx)/2 - ((clen-stringx)/2) + xpos 
/xpos exch def Я ((clen-stringx)/2) + xpos - - 
xpos UpOS moveto %--- 

Str show %--- 

) def 


exch def is one of the mostcommon sequences in PostScript 
programs. Recall that def requires a literal name anda value, with 
the value on top of the stack. To set a variable equal to a value 
that'son top of the stack, push the literal name on top of the value 
and then use exch to get the elements in the correct order for def. 

In case there's any doubt about how to call CenterString, 
here's a sample program that uses it: 


% set the font 

/Times-Roman findfont 54 scalefont setfont 
% center on 8” page 

@ 371 612 (Hello, World!) CenterStr ing 
showpage % draw and eject the page 


The LaserWriter Driver 

The job of the LaserWriter driver is to convert whatever is 
drawn on the screen (by QuickDraw) into PostScript for the 
printer. Though the concepts involved in the translation are fairly 
simple, the implementation is almost frighteningly complex. 

When you open a printing port on the Macintosh, the printer 
driver replaces all of the low-level drawing procedures with 
procedures that drive the printer. This is done by resetting the 
thirteen quickdraw primitives that draw basic objects on the 
screen, with an alternative set of drawing primitives that draw to 
the printer. These replacement procedures are contained in the 
printer resource file, LaserWriter. [For more information on this 
aspect of the problem, see the printer driver article in the Nov. & 
Dec. issue of MacTutor. -Ed] In the case of the LaserWriter 
driver, the replacement procedures generate a PostScript pro- 
gram that will reproduce the page on the printer. However, the 
generated code is not “pure” PostScript, it relies heavily on a 
library of PostScript procedures or macros, that are designed to 
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emulate QuickDraw routines. These procedures are defined in 
the LaserPrep file and are downloaded to the LaserWriter before 
any pages are printed. You can see what these definitions are by 
typing cmd-K after hitting the print button in the print dialog. 

The LaserWriter file contains the replacements for the 
drawing routines and the PAP (Printing Access Protocol) man- 
ager, which coordinates communications with the LaserWriter 
over AppleTalk. LaserPrep contains the definitions of the Post- 
Script routines that emulate QuickDraw. These routines are 
placed in their own dictionary, and they’re downloaded in a 
special way that allows them to remain in memory until the 
LaserWriter is turned off. Before the driver prints, it always 
checks if the LaserPrep dictionary is in memory; if it’s not, Laser 
Prep is downloaded while you watch the message “initializing 
printer...” Once downloaded, the dictionary consumes at least 
62k of LaserWriter memory. Note that Pagemaker uses it’s own 
prep file called AldusPrep. Having both of these in the printer 
memory at the same time can sometimes run the printer out of 
memory. Too bad the printer can’t automatically swap prep files 
in and out to avoid this problem! 

When I first became acquainted with PostScript, it was clear 
that many PostScript features weren’t accessible through the 
driver because QuickDraw didn’t support them. I considered 
modifying the driver, but soon found that I lacked the patience 
necessary to do so. LaserPrep contains more than 100 PostScript 
routines, many of which rely on other routines defined by the 
driver. Tracing through a single one can involve jumping to 
fifteen or twenty different places in the source. Even worse, the 
names given to the routines are literally cryptic (names were 
reduced to several characters to save space) and there was no 
LaserPrep documentation. Apple has since documented the 
LaserPrep routines (Appendix B of the LaserWriter Reference 
Manual), but I still wouldn't recommend driver modifications to 
anyone lacking endurance. If you’re ready to test your patience, 
you can alter LaserPrep using FEDIT. 

There are two common tricks that are indispensible when 
studying the driver. To save the PostScript code generated bya 
program that uses the standard LaserWriter driver, press Com- 
mand-F as the LaserWriter printing dialog disappears. The code 
will be stored in a TEXT file named “PostScript” instead of being 
send to the LaserWriter. To save the code generated as well as the 
driver’s PostScript replacement routines, press Command-K as 
the printing dialog disappears (it will also be stored ina TEXT file 
named “PostScript”). 

Under some circumstances, the saved code can simply be 
downloaded to the LaserWriter. Unfortunately, though, simple 
downloading is not always enough. Under normal printing con- 
ditions, the driver downloads the LaserPrep file (if necessary) as 
well as any downloadable fonts used in the document. Unless the 
downloader you’re using is intelligent and can perform these 
functions, you might not be able to get “Command-F” files to 
print successfully. The downloader presented with this article 
simply sends PostScript code to the LaserWriter and is best for 
downloading pure PostScript files. [It appears that the new 
version of the driver downloads fonts at the start of the job, 
because a cmd-K after printing a Reflex Plus report had both the 
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prep file and the downloaded laser font definition contained 
within it, so that it could be directly downloaded to the Laser- 
Writer at a later date. This change may have been made to 
accomodate the new batch printing of MultiFinder. -Ed] 


The Failure of WYSIWYG 

In the days of the IBM PC and the daisywheel printer, the 
choice between a WYSIW YG word processor and a code-based 
word processor was largely a matter of preference. WYSIWYG 
was useful because the capabilities of the screen usually matched 
those of the printer. Though the Macintosh and the Laser Writer 
represent significant advances in technology, there are differ- 
ences between what can be done using the Mac's screen with 
QuickDraw and what can be done on the LaserWriter using 
PostScript. These differences make WYSIWYG all but useless 
for dedicated publishing. The production of high-quality printed 
materials involves typographical refinements (fractional point 
sizes and leadings, kerning, hairline rules, etc.) much too subtle 
to be displayed on the Mac’s screen. Though there are some page 
layout programs that provide the user with control over these 
refinements, they can't be displayed. This forces the user into an 
iterative process — pages have to be printed and reprinted until 
everything looks right. Reprinting highlights the flaws in the 
system software and hardware. The rather baroque translation 
from QuickDraw to PostScript is slow and the size of the 
memory-resident LaserPrep dictionary leaves little room on the 
LaserWriter for downloadable fonts or larger page sizes. Conse- 
quently, the printing of documents that use non-resident fonts is 
slowed to a crawl by the downloading and re-downloading of 
fonts and AppleTalk gets rather tied up as well. When it takes 
twenty minutes to print a page, one is lucky to make deadlines — 

much less worry about refinements. 

There are no easy solutions to these problems. The screen 
resolution difficulties can only be solved by very high resolution 
displays and QuickDraw modifications. The translation problem 
can be eased with a large dose of additional memory (impossible 
on current LaserWriters) and a dedicated font downloader 
(kludge) . The clean solution, of course, is to provide programs 
with the ability to generate pure PostScript and output it directly 
to the LaserWriter. It's clear that this ability will become a 
common feature of all software (not just page layout programs) 
inthe future; witness the rise of *encapsulated postcript" as a way 
of blocking out postscript graphics on the page in a program like 
Pagemaker. 


Sources of Information 
You'll find the following sources useful when learning 
PostScript. 


PostScript Language Reference Manual 

(Red Book) 

PostScript Language Tutorial and Cookbook 

(Blue Book) 

Poscript Language Journal 

The Red Book begins with a comprehensive description of 
PostScript and some important examples. The remainder of the 
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book covers all the PostScript commands and provides some 
specific information about the LaserWriter. The Blue Book is 
(as its full title implies) a tutorial with many documented ex- 
amples. Since these books are published by Addison-Wesley, 
you can purchase them at most technical bookstores. Watch for 
the rumored Green book that will cover advanced programming 
techniques. 

Postscript Language Journal is a technical Journal de- 
voted to postscript programming and related Postscript based 
Mac products. Published by Pipeline Associates, PO Box 5763, 
Parsippany, NJ 07054. Only $15 per year, quarterly. Highly rec- 
ommended. 

Adobe's telephone support is phenomenal, so phenomenal 
that it almost makes up for the fact that they distribute no 
technical notes about PostScript. Call them for help, or informa- 
tion about their PostScript programming classes. Adobe Systems 
Incorporated, 1585 Charleston Road, P.O. Box 7900, Mountain 
View, California 94039-7900 (415) 961-4400. 

Understanding PostScript Programming 

by David A. Holzgang. 

Sybex, Inc., 1987. 

This is the first “3rd Party" book about PostScript and it 
appears to be a much more readable introduction to the language 
than Adobe's Blue Book. The example programs aren't quite as 
complex, which is good, and they're explained in detail. Sybex, 
Inc. 2021 Challenger Drive, #100, Alameda, California 94501 

Apple LaserWriter Reference 

This document contains invaluable information about print- 
ing with the LaserWriter driver. fKKNBLRM, from A.P.D.A.,290 
SW 43 Street, Renton, Washington 98055 (206) 251-6548 

‘PostScript Halftoning" 

by Henry Bortman. 

A three part series in the November '86, December '86 and 
January '87 issues of The Macazine. Bortman gives a very 
detailed explanation of how shades of gray are rendered by 
PostScript. Back Issues/The Macazine, P.O. Box 9802-919, 
Austin, Texas 78767 (800) 624-2346; $3.75lissue 

Principles of Interactive Computer Graphics 

by William M. Newman and Robert F. Sproull. 

McGraw-Hill, 1979. 

This book doesn't cover PostScript, but it presents some of 
the mathematical concepts behind PostScript' s implementation. 
It also describes three-dimensional drawing and shading tech- 
niques. It's available at technical bookstores. 


Hooking Up 
There are two ways to run PostScript programs on the 
LaserWriter. The LaserWriter's PostScript interpreter can oper- 
ate interactively (like BASIC or FORTH) or it can accept 
programs downloaded from the Macintosh. 
Follow these steps to program interactively: 


е Turn the LaserWriter off. On the side with the ports, 
you'll find a mode switch. Set the switch to 9600. 

e Connect the printer to the Macintosh using a null 
modem cable (the original Apple Personal Modem 
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cable works). Use the 25-pin (RS-232) serial porton the 
LaserWriter. 

* Start up your favorite communications software on the 
Macintosh. Setup: 9600 baud, 8 bits, no parity, half 
duplex. 

“ Type executive. The PostScript copyright lines will be 
appear, followed by the system prompt, PS>. You’re 
now in the interactive mode. 


The following sections present a downloader that sends 
PostScript TEXT files to the LaserWriter. There are also a 
number of text editors that have integral downloaders: 


JustText, from Knowledge Engineering, P.O. Box 2139, 
New York, New York 10116. 212.473.0095. 

PostHaste, from Micro Dynamics, Ltd., 8444 16" Street 
#802, Silver Spring, Maryland 20910. (301) 589-6300. 

QuickScript, (under development) from Perimeter, 1608 N. 
Milwaukee, Chicago, Illinois 60647. (312) 278-9509. 


About the Downloader... 

The downloader presented here, PS PRINT, provides a 
convenient way of sending PostScript programs to the Laser- 
Writer. When it launches, you'll be presented with a file dialog 
containing the names of TEXT files. The file you select will be 
downloaded to the LaserWriter. When the download ends, you'll 
be given a chance to save any printer feedback to a text file. Then 
the original file dialog will appear again, allowing you to down- 
load another file. If you click on Cancel, a file dialog containing 
applications will appear. You can use it to transfer to another 
application, or return to the Finder by clicking on Cancel. 

There are many ways to send PostScript to a printer over 
AppleTalk. They range from writing your own AppleTalk rou- 
tines to using high-level print manager functions (see the Apple 
LaserWriter Reference for details). PS PRINT uses the PAP 
manager. 


The PAP Manager 

Communication with the LaserWriter is accomplished via 
the PAP manager, which provides a high-level interface to 
AppleTalk. Its code resides in resources that are contained in the 
LaserWriter file. Oddly, the syntax of the PAP calls doesn't 
appear to be documented in the Apple Laser Writer Reference and 
there have been modifications to the calls since their initial 
presentation in Appendix E of Inside LaserWriter. The following 
information about the PAP calls is a revised version of the 
information that appeared in Appendix E. The declarations are 
presented in Lightspeed C (note that Lightspeed integers occupy 
16 bits). These declarations are here to detail the requirements of 
the PAP routines. They're not declared this way in the down- 
loader. 


pascal int PapOpen(ConnectId, LaserName, FlowQuantum, 
LaserStatus, OpenState) 


int *Connect Id; 
char *LeserName; 
int FlowQuantum; 
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papstatusptr LaserStatus; 
int *OpenState; 


PapOpen is used to establish a connection between the 
Macintosh and the LaserWriter over AppleTalk. It is executed 
asynchronously. This means that, though control returns to the 
caller, the connection does not necessarily open immediately. If 
the call returns with a nonzero value, the connection cannot be 
opened. Otherwise, OpenState will be set to a positive value 
while the connection is opening. When the connection is open, 
OpensState will be set to zero. If the opening fails after control 
has returned to the caller, OpenState will be set to a negative 
value. 

LaserName should point to an AppleTalk EntityName 
(see the AppleTalk Manager section of Inside Macintosh). 
Usually this will be the name of the printer selected with the 
Chooser. The Chooser stores this name in the LaserWriter file 
resource PAPA -8192. 

The FlowQuantum is the number of 512 byte buffers that 
are available for sending and receiving information. The Laser- 
Writer uses a 4096 byte buffer (FlowQuantum = 8), so it's 
probably most efficient if the Macintosh uses a buffer of that size 
as well. 

The LaserStatus buffer contains a status message that's 
updated during the opening of the connection. Its structure is 
declared in the downloader source. The buffer is not cleared by 
PapOpen, so you should clear it if you intend to use it (PS 
PRINT does not). 


pascal int PapWrite(ConnectId, WriteBuffer, WriteSize, 
WriteEof, WriteState) 


int Connect Id; 
char *WriteBuffer; 
int WriteSize; 
int Wr itEof ; 

int *WriteState; 


PapWrite is an asynchronous call that is used to send data 
to the LaserWriter. Like the other asynchronous PAP calls, it uses 
the Connectld that's set by PapOpen and it will return a 
nonzero value if communications have failed. While it is sendin g 
the data, WriteState will be positive. If the transfer is successful, 
WriteState will be set to 0. Note that this does not mean that the 
data in the buffer has been processed by the LaserWriter; it has 
merely been received. If communications fail, WriteState will 
become negative. 

The data being sent is placed in the buffer pointed to by 
WriteBuffer. The maximum size of this buffer is determined by 
FlowQuantum (see PapOpen). The application should set 
WriteSize to the actual size of the data being sent. 

Before the last buffer of data is sent to the LaserWriter, the 
application should set WriteEof to a positive value. This signals 
the LaserWriter to notify the application (via PapRead) when it 
has completed processing the job. 


pascal int  PapRead(ConnectId, ReadBuffer, ReadSize, ReadEof, 
ReadState) 
int Connect Id; 
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сһаг *ReadBuf fer ; 
int *DataSize; 
int *ReadEof ; 
int *ReadState; 


PapRead is an asynchronous call that is used to read 
feedback from the LaserWriter. PAP requires continuous com- 
munications between the Macintosh and the LaserWriter. When- 
ever a connection is open, you must repeatedly call PapRead 
(using the connection’s ConnectId) to ensure that data coming 
from the Laser Writer is received by the Macintosh. 

If communication has failed, PapRead will return a non- 
zero value, or ReadState will (possibly later) be set to a negative 
value. If a PapRead has not yet completed, ReadState will be 
positive. When it's finished, ReadState will be zero. 

If there is feedback from the Laser Writer, ReadSize will 
contain the number of bytes of feedback and the feedback itself 
will have been placed in the buffer pointed to by ReadBuffer. 
The size of the buffer is given by FlowQuantum (see 
PapOpen). 

ReadEof is used to monitor the end of the information flow 
between the Mac and the LaserWriter. Just before the last 
PapWrite call, the application should set WriteEof to a positive 
value. This informs the LaserWriter that the final buffer is being 
sent. Once the buffer has been processed by the LaserWriter, а 
call to PapRead will return with ReadEof set to a nonzero 
value. At this point, it’s safe to close the connection using 
PapClose. One can simply close the connection after the final 
PapWrite’s WriteState becomes 0 (when the last buffer has 
been sent successfully) without waiting for a positive ReadEof, 
but this will eliminate the possibility of receiving any feedback 
generated by the final buffer. 

pascal int PapCloseCConnectId) 

int ConnectId; 

This call closes the connection referenced by Connectld. 

pascal int PepUnloadO 

This routine is usually executed after PapClose. It unloads 
PAP's private data structures and closes any connections that 
remain open. 


pascal int PapStatus(LeserName, LeserStatus, LaserNode) 
char *LaserName; 
papstatusptr LeserStatus; 


long *LaserNode; 

This is a synchronous call that checks the status of the named 
printer. It can be executed even if there isn’t an open connection 
with the printer. 

LaserName should point to an AppleTalk EntityName 
(see the AppleTalk Manager section of Inside Macintosh). 
Usually this will be the name of the printer selected with the 
Chooser (see PapOpen above). 

LaserStatus is a buffer that will contain the status 
information requested by the call. Its structure is declared in the 
downloader source. 

The value pointed to by LaserNode should be set to zero the 
first time the routine is called. PapStatus will set it to the 
printer’s AppleTalk address. Subsequent calls will execute more 
quickly using the node address. 
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The PAP manager routines described above (and a few more 
that aren’t relevant to downloaders) are stored as resource PDEF 
10 in the LaserWriter file. The entry points for the routines occur 
at the beginning of the resource. The downloader reads the 
resource into memory before any of the calls are made. In the 
downloader, I’ve created glue routines with the same names as 
the PAP calls. As mentioned earlier, they do not have the above 
declarations. In PS PRINT, all of the variables in the above 
declarations are declared as globals. Each PAP glue routine 
pushes these globals onto the stack and JSRs to the routine’s 
entry point. 

The source for this downloader is based on code presented 
in Mike Schuster's “Laser Print DA for Postscript" (MacTutor, 
February 1986) and Alan Oppenheimer’s downloader, which 
was published in Appendix E of the original Inside LaserWriter. 


Try К 
Download the following code to the LaserWriter. Try ex- 
perimenting with it — I’ve included some comments regarding 
parameters that you might want to change. 


% This routine draws a string 3 times. Each time it is 
% offset and drawn with a different shade of gray. 

$ If you want to experiment, use different values for 
% setgray Canything between 0 and 1) 


кн 


/thestring exch def 
currentpoint 
.6 setgray 
thestring show 
move to 
-4 4 rmoveto 
currentpoint 
.2 setgray 
thestring show 
move to 
-4 4 rmoveto 
1 setgray 
thestring show 
} def 


% setscreen is used to change the shading method. 

% Normally, shades of gray are rendered with dots 

% of various sizes. These arguments to setscreen 

% make PostScript render grays with lines of varying 

% weights instead of dots. For more info, consult the 
% Red Book and Colophon, Volume 2 


$ the first argument (35) is the # lines/inch and the 
$ second is the degree at which the lines are drawn. 
% Try different values. 

35 45 (exch pop ebs 1 exch sub) setscreen 


% draw and fill! the square on which the text will sit 
50 280 moveto 

50 500 lineto 

480 500 lineto 

480 280 lineto 

50 280 lineto 


‚9 setgray 
#111 


€ set the font 
/Times-Bold f indfont 72 scalefont setfont 
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$ move into position 
100 382 moveto 


"define SIMPLEALERT 1000 
/* File-related */ 


int FErr; 
Я skew the space. concat does а linear int FileRef ; 
% transformation of the СТМ by the matrix SFReply UserReply; 
$ that precedes it. Read the Red Book and SFTypeList ^ Fylz; 
$ dig out your linear algebra textbook. Point SFPoint; 
[1.11100 ] concat char *OpenNeme; 
cher NullString; 
$ Substitute whatever you want for the text wihtin EventRecord  theEvent; 
% the parentheses Handle DummyHand 1; 
(MacTutor) ShadowShow Rect DummyRect; 
long DummyType; 


% inverse-transform these absolute coordinates. 
% we want their equivalents in the skewed space 
100 318 [1.111001] itransform moveto 
(Magazine) ShadowShow 
showpage 

Downloader Source 
/* PS PRINT: A PostScript Downloader 


written by Nicholas Pavkovic 
© Perimeter, 1987. 


PERIMETER 
1688 North Milwaukee Avenue 
Chicago Illinois 60647 
312 . 278 . 9509 
Portions copyrighted by THINK Technologies, Inc., 
and Apple Computer, Inc. 
Compiled with LightspeedC™ 
Libraries linked: MacTraps, sprintf /sscanf */ 
"include «МасТурев.һ» 
#include «QuickDraw.h» 
"include <EventMgr .h» 
8include <StdFilePkg.h» 


/* FileMgr.h Defs Cdon’t need whole file) */ 
8def ine fnfErr -43 

"def ine eofErr -39 

extern int FSFCBLen : 2x3F6; 

extern int BootDrive : 0x210; 

extern int SysMap : 0хА58; 


"define FromProgram 0 
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/* Windows */ 
long PrintWinPtr; 
long DirectWin; 


/* Please include InfoWin if you compile and distribute 
the program */ 


long InfoWin; 


char *InfoString = А PostScript Downloader written by 
Nicholas Pavkovic\r\r@ Perimeter 1987.\rPortions © THINK and 
Apple Computer, Inc.\rNon-commercial distribution is permit- 
ted. V 

\r\rPERIMETER\r 1608 North Milwaukee Avenue Mr Chicago 
Illinois 60647\г3 12 . 278 . 9509\г \ 

Developers of LaserLabels™ and QuickScript™\r\ro Click on 
the mouse to continue. ; 


/* PAP globals */ 

on struct 
long int systemstuff ; 
char statusstr [256]; 

) papstatusrec, *papstatusptr; 


papstatusrec LaserStatus; 


Handle pap; 
lo apaddr ; 
/% WindowMgr.h (don’t need whole file) */ ine Fico рт 
def ine NewWindow Clong) NewWindow long unsigned LaserNode; á 
"define dBoxProc 1 int OpenState: 
int WriteState; 
/* General */ int ReadState; 
"def ine True 1 int Connect Id; 
"define False 0 int Wr iteEof : 
"def ine Success 0 int ReadEof ; 
"define Failure E. cher ReadSpace [ 4096); 
cee nila ч cher *WriteBuffer; 
"define NULL ØL int WriteSize; 
int ReadSize; 
/* Fall-through functions */ char *LaserNane; 
Handle LaserHand; 
"define IssueRead()  if( issueread() Fails ) return( char LaserNaneBuf f 1641; 
Failure ) | | char VirtualPege(40961; 
#def ine CheckIf Cancel led() if€ checkifcencelledC) char MessageBuf f [2561; 
Fails ) returnC Failure ) Handle FeedbackHandle; 
8def ine DisplayStatus() ifC displaystatus() Fails long FHandleSize; 
) return( Failure ) lo LastStatusDisplau: 
define OpenLChannelC) if( openlchannelO) Fails ) return f*SinpleAlert: ы 
Failure) | Implements а general alert used for most of the terminal 
"def ine PostMessage(x, y ) 1ҒС postmessage(x, у) error messages.*/ 
Fails ) return. Failure ) SimpleAler t( тб ) 
char *m0; 
/* PostMessage selectors */ 
ее праг: 3 РагапТехіС mB, OL, OL, OL ); 


NoteAlertC SIMPLEALERT, ØL ) ; 
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/* SFDFilter: 
Filter function for Stenderd File 018109. 
Makes the “Open” button context sensitive 
end gives it а heavy outline.*/ 

pascal Boolean SFDFilter( 4100, event, itemhit ) 

long 9109; 

EventRecord — *event; 

int *itemhit; 


if С event what == activateEvt && event-»modif iers & 
activeFlag ) 


GetDItemC dlog, getOpen, &DummyType, &DummyHand 1, 
&DummyRect 2; 

SetCTitleC DumnyHand1, OpenName ); 

PenSize(3, 3); 

InsetRect( &DummyRect, -4, -4 ); 

FrameRoundRect( &DummyRect, 16, 16); 

PenSize( 1, 1); 


) 
return( False ); 


/* displaystatus: 

Checks and display status every second, 

even if routine is called more frequently. */ 
oe 


S TickCount() - LastStatusDisplay > 60 2 


PepStatus(); 
PostMessage( &LaserStatus.stetusstr, FromPrinter ); 
LastStatusDisplau = TickCount(); 


| CheckIfCancelledO; 
/* Directions: 
Display text in the directions window.*/ 
Directions( text ) 
char *text ; 


DummyRect.top = 10; 
DummyRect.left = 10; 
DummyRect .right = 342; 
DummyRect .bottom = 80; 


SetPortC DirectWin ); 
MoveToC 10, 16 ); 
TextBoxC &text[1], (long) 4ех{ [0], &DummyRect, 0 ); 


co 


cher *source, *dest; 
int counter; 
int sysVRef ; 


InitGraf (&thePort); 

InitFonts(); 

InitWindows(); 

TEInit(); 

InitDialogs(COL 5; 

FlushEventsCeveryEvent, 02; 

InitCursor(); 

/*Read PAP routines into memory. 

OpenResFile uses PMSP; we need only to find boot 
drive. See Tech Note 877 for details. x 


ifC FSFCBLen 2 
ҒЕгг = GetVRefNumC SysMap, &sysVRef ); 
else 


sysVRef = BootDrive; 


SetVolC &NullString, sysVRef 2; 
FErr = OpenResFile(C\pLaserWr iter); 
ifC FErr == -1 ) 


SysBeep( 1); 

SinpleAlertC \pThe LaserWriter file could not be 
found or couldn't be opened. Returning to Finder. 2; 

return; 


/* Read the PAP code into memoru */ 
if € © pap = GetResource( PDEF, 10 ) ) == NULL || 
шайы” ) 


SysBeep( 1); 

SimpleAlertC \pThe PAP routines could not be 
loaded. Returning to Ғіпдег. 2; 

ifC FErr != -1 ) CloseResFile(C FErr 2; 

return; 


J 


/* Detach PAP */ 
HLock(pap); 
DetachResource(pap); 
papaddr = (long) “рар; 


/* Read printer name from LaserWriter file */ 
if С С LaserHand = бе Кезоугсе( PAPA, -8192 ) ) == 
NULL || еи ) 


ЗузВеер( 1); 

SimpleAlert( \pThe LaserWriter name could not be 
read. Returning to Finder. 2; 

return; 


д 


/* Create а С string version of the printer name (Гог 
messages) and place it into LeserNemeBuff */ 


HLockC LaserHand ); 
DetachResource( LaserHand ); 
LaserName = *LaserHand; 


/* Сору the printer name into LaserNameBuff , 
а С string version used for messages to user.*/ 


source = (char *) LaserName + 1; 

dest = LaserNameBuf f ; 

counter = Cint) *LeserNeme; 

whileC counter- ) *dest++ = *source**; 
*dest = 0; 


/* Done with LaserWriter file */ 
CloseResFileC FErr ); 


/* About PS PRINT... */ 
DummyRect. left = 62; 
DummyRect.top = 36; 
DumnyRect.bottom = 318; 
DummyRect.right = 446; 
InfoWin = NewWindow( OL, &DummyRect, &NullString, 
OxFF, dBoxProc, -1L, False, ØL ); 
SetPort( InfoWin 2; 
TextFaceC condense ); 
TextFontC 0 ); 
МоуеТо( 10, 36 ); 
DrewStringC \pPS PRINT ); 
PenPat( grau 2; 
MoveToC 64, 26 ); 
PenSizeC 1, 12 ); 
LineTo( 362, 26 ); 
PenNormalC); 
TextFont( 1 2; 
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DummyRect.top = 46; 

DummyRect. left = 10; 

DummyRect.bottom = 282; 

DumnyRect.right = 362; 

TextBoxC InfoString, 314L, &DummyRect, -1 ); 

whileC GetNextEvent( everyEvent, &theEvent) == Ø || 
theEvent.what != mouseDown ) SystemTask(); 


DisposeWindowC InfoWin ); 


/* Setup instruction window. */ 
DummyRect.left = 80; 
DummyRect.top = 36; 

DummyRect .bottom = 90; 
DummyRect.right = 428; 


/*Technically, there’s no reason that the directions 
window should be a dialog, but doing so avoids the bug 
described in Tech Note #99 (SFD doesn’t update file list when 
. new disk inserted).*/ 


DirectWin = (long) NewDialog( ØL, &DummyRect, 
&NullString, 9xFF, dBoxProc, ØL, 0, OL, ØL ); 


SetPortC DirectWin 2; 
TextFaceC condense ); 
TextFontC 0 ); 


FeedbackHandle = NewHandle( 0 ); 
if€ FeedbackHandle == Ø || MemError() 2 


SimpleAlert( \pCan’t Allocate Feedback Handle. 
Returning to Finder. ); 
return; 
SFPoint.v = 108; 
/* Download loop */ 
whileC 1) 


SetHandleSize( FeedbackHandle, ØL ); 
FHandleSize = 0; 


/* Select file to download */ 


DirectionsC \ро Select а file to download, ог\го 
Click on Cancel to transfer or return to the Finder ); 

SFPoint.h = 80; 

Fylz(g] = TEXT; 

OpenNeme = \pDownload; 

SFPGetFileC SFPoint, &NullString, ØL, 1, Fylz, 
OL, &UserReply, -4000, SFDFilter ); 


/* If file selected, download , otherwise transfer */ 
if С UserReply.good ) 


TextDownloadC &UserReply.fName, 
RUNE 2; 


else 


DirectionsC \ро Select an application to 
transfer to, ог\го Click on Cancel to return to the Finder ); 

Fylz[0] = APPL; 

OpenName = \pTransfer; 

SFPGetFileC SFPoint, &NullString, (ProcPtr) 
0, 1, Fylz, ØL, &UserReply, -4000, SFDFilter); 


DisposDialog( DirectWin ); 
/* If user cancels, return to Finder */ 


O The Definitive MacTutor, Vol. 4 


if С !UserReply.good ) return; 
MessageBuff [0] = 0; 
SetVolC &MessageBuff, UserReply.vRefNun ); 
Launch( 8, &UserReply.fName ); 
2 


/* If feedback received, save it to а file. */ 
C FHandleSize ) 


DirectionsC \ро Enter а filename to save the 
printer feedback, ог\го Click on Cancel to continue 2; 


TryAgain: 


SFPoint.h = 104; 
SFPutFileC SFPoint, \pSave the feedback as:, 
\pFeedback, OL, &UserReply ); 


/* If cancelled, loop to downloading code */ 
if С !UserReply.good ) continue; 
РЕгг = FSOpenC &UserReply.fName, 
UserReply.vRefNum, &FileRef ); 


/* If the specified file doesn’t exist, create it */ 
ifC FErr == fnfErr ) 


( 

SetVol( &NullString, UserReply.vRefNum); 

ГЕгг = CreateC &UserReply.fName, Ø, EDIT, 
TEXT 5; 


FErr = FSOpenC &UserReply.fName, 
UserReply.vRefNum, &FileRef ); 


4 


à FErr != Ø ) 


PtoCstr( &UserReply.fName ); 

өргіп С &MessageBuff,The file you re- 
quested, “$s”, is not currently available. Error: ха, 
&UserReply.fName, ҒЕгг ); 

CtoPstr( &MessageBuff ); 

SimpleAlert( &MessageBuff ); 

a TryAge in; 


Н оск( FeedbackHandle ); 

DummyType = FHendleSize; 

SetFPosC FileRef, 1, ØL ); 

FSWriteC FileRef, &DummyType, *Feedback- 


Handle ); 
SetEOFC FileRef, DummyType ); 
FSCloseC FileRef ); 
HUnlockC FeedbackHandle ); 
); 
) 
ү шырыш 


long CurrentTime, StertOpening; 


DirectionsC Apo Press 1021. CCommand-Period) to cancel 
the download); 


/* Set up print window. */ 
DummyRect.top = 108; 
DumnyRect.left = 80; 
DummyRect.bottom = 296; 
DummyRect.right = 428; 


PrintWinPtr = NewWindowC ØL, &DummyRect, NullString, 
OxFF, dBoxProc, -1L, False, ØL ); 

SetPortC PrintWinPtr 2; 

TextFontC 0 ); 
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TextFace( condense ); ) 
PenSizeC 1, 1); 


PenPat( black 2; issueread() 
МоуеТо( 10, 24 ); long oldsize; 
LineToC 12, 24 ); cher *fbptr, *readptr; 
MoveToC 14, 28 ); 
DrewStringC \pProgram 2; if С ReadState <= 0 2 
Моуе( 2, -4 5; 
LineToC 338, 24 ); /* Negative ReadState indicates communications failure */ 
LineToC 338, 86 ); if С ReadState < 0 ) 
LineToC 10, 86 ); 
LineToC 10, 24 ); EndPCom( ); 
return( Failure 2; 
MoveToC 10, 108 ); ); 
LineToC 12, 108 ); /* 
MoveToC 14, 112 ); ReadState == 0 => successful read. 
DrawString( \pPrinter 2; ReadSize)® => There's feedback. 
Move( 2, -4 ); */ 
LineToC 338, 108 ); if С ReadSize > 0) 
LineToC 338, 170 ); ( 
LineToC 10, 170 ); SysBeep( 1); 


LineToC 10, 108 ); 
/* Feedback messages use ASCII 10 


TextFontC 1 ); (linefeed) instead of ASCII 13 (carriage 
return). Convert them and display. x/ 

/* Open connection to server — */ 

sprintf( &MessageBuff, Looking for printer “55.7, readptr = &ReadSpace[ ReadSize - 11; 
&LaserNemeBuff ); ifC *readptr == 10 ) *readptr = 13; 

CtoPstr( &MessageBuff ); *(+treadptr) = 10; 

PostMessage( &MessageBuff, FromProgram ); CtoPstr(&ReadSpace); 

FlowQuantum = 8; PostMessage( &ReadSpace, FromPrinter ); 

ConnectId = 0; DelayC Clong int) 158, &DummyHand1); 


if С PapOpen() 2 
/* Update the feedback handle’s size and 


NoPr inter C); copy feedback. */ 

return( Failure 2; 
); oldsize = FHandleSize; 

FHandleSize += ReadSize; 
sprintf( &MessageBuff, Establishing connection with SetHandleSize( FeedbackHandle, FHandleSize); 
“45.7, &laserNameBuff ); 

CtoPstr( &MessageBuff 2; 1С МепЕггог() == noErr ) 
Роз{Меззаде( &MessageBuff, FromPrinter ); ( 
StertOpening = TickCount(); readptr = &ReadSpace[ 1); 
whileC OpenState › 0) бөріг = (char *) *FeedbackHandle + oldsize; 
( whileC ReadSize- ) *fbptr** = *readptr**; 


DisplayStetus(); 
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); 

CurrentTime = TickCount(C); , 

if( CurrentTime - StartOpening > 1800 2 жаа (ead t 
| if (PapRead() 2 


NoPr inter(); 
return( Failure 2; EndPCon( ); 
); ; return( Failure ); 
CheckIfCancelled(); CheckIfCencel led, 
| else 
if С OpenState < Ø ) 
NoPr inter (2; /* Since ReadState > 0, lest read not finished */ 
returnC Failure 2; DisplayStatusC); 


i return( Success ); 
PostMessage( \pConnection established., FromProgrem ); 


ReadState = 0; CloseLChanne1() 
WriteState = 0; ( 

ReadEof = 0; IssueRead( ); 

WriteEof = 0; /* set end-of-file */ 
ReadSize - 0; WriteEof = 1; 


WriteSize - 0; 


/* Send empty buffer */ 
return( Success ); WriteBuffer = ; 
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WriteSize = 0; 
if С PapWriteC) 2 


EndPCom( ); 
return( Failure ); 


7 
/* Wait for printer to indicate that processing is over */ 
while С ReadEof == 0) IssueReadC); 
PepClose(C); 
PapUnload(); 
DisposeWindowC PrintWinPtr ); 
return( Success ); 


) 
/*  EndPCom: 

Closes connection immediately.*/ 
ii 

PepCloseC); 

PapUnload(); 


DisposeWindow( PrintWinPtr ); 

sprintf( &MessageBuff, Communication with the printer 
“Zs” has ended., &LaserNameBuff ); 

CtoPstr( &MessageBuff ); 

SimpleAlert( &MessageBuff ); 


/*postmessage: 
Displays messages from printer and program in PrintWin.*/ 


postmessage( s, source ) 
char *s; 
uh Source; 


DummyRect.left = 13; 


DummyRect .right = 335; 
г” source == FromProgram ) 


DummyRect.top = 35; 
DummyRect.bottom = 83; 


else 


DummyRect.top = 119; 
DummyRect.bottom = 167; 


Тех4Вох( ks[1], (long) 8101, kDummgRect, 0 ); 
CheckIfCancelled(); 
return( Success ); 

/* checkifcancelled: 


Checks if user has cancelled the download with 
Command-Per iod. */ 


checkif cancelled) 
e GetNextEvent( everyEvent, &theEvent) == 0 ) 


SystemTaskC); 
returnC Success ); 


); 
ifC theEvent.what == keyDown && 
theEvent.modifiers & cmdKey && 


(theEvent message & charCodeMask ) == . ) 
EndPCom( ); 
return( Failure ); 


) 

/* TextDownload: 
Downloads the specified file to the printert/ 
TextDownload( FFileName, Vnum ) 

$4255  *FFileName; 

int Vnum; 
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long ItemsRead; 
longFileSize, Remaining; 
$tr255 — WorkingMessage; 
OpenLChanne1(); 


FErr = FSOpen( FFileName, Vnum, &FileRef ); 
PtoCstrC FFileName ); 


if С ҒЕгг |с noErr ) 


CloseLChannelC); 


sprintf( &MessageBuff, Sorry, the file “45” could 


not be opened. Error: %d, FFileName, ҒЕгг ); 
CtoPstr( &MessageBuff ); 
SimpleAlert( &MessageBuff ); 
returnC Failure 2; 


2 


GetEOF( FileRef, &FileSize ); 
Remaining = FileSize; 


үші Remaining ) 


sprintf( &WorkingMessage, Downloading 
*%s*\rComplete: %1d%%, FFileName, 100 - ((Remaining * 100 )/ 
FileSize) ); 


CtoPstr( &WorkingMessage ); 
PostMessage( &WorkingMessage, FromProgram ); 


ItemsRead = 4096; 
ҒЕгг = FSRead( FileRef, &ItemsRead, &VirtualPage); 
if € ItemsRead == 0 && FErr |= eofErr ) 


CloseLChanne1(); 
goto ErrorExit; 


s if € FErr == eofErr ) 


WriteSize = Cint) ItemsRead; 

1С sendtoprinter( VirtualPage, Cint) 
ItemsRead 2 Fails ) goto ErrorExit; 

FSCloseC FileRef ); 

sprintf( &MessageBuff, "$s" has been 
downloaded., FFileName, FileRef ); 

CtoPstr( &MessageBuff ); 

PostMessage( &MessageBuff, FromProgram); 

CloseLChannelC); 

return( Success ); 
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if( sendtoprinter( VirtualPage, Cint) ItemsRead ) Fails ) 
goto ErrorExit; 
Remaining -= ItemsRead; 


2 


ErrorExit: 
FSClose( FileRef ); 
sprintf( &MessageBuff, Sorry, the f ile “$s? could not 
be downloaded., FFileName ); 

CtoPstr( &MessageBuff ); 
SimpleAlert( &MessageBuff ); 

returnC Failure ); 

/* sendtoprinter: 
General downloading routine (8150 handles 
buffers > 4096 bytes)*/ 

sendtoprinter( bffer, bffsize ) 

char *bffer; 

e bffsize; 


register cher *bffptr; 
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bffptr = bffer; 
whileC bffsize › 0) 


1С bffsize > 4096 ) 


WriteSize - 4096;) 
еізе 


WriteSize = bffsize;); 
WriteBuffer = bffptr; 
IssueRead(); 
if С PapWriteC) ) 


EndPCom( ); 
return( Failure );); 
CheckI fCance] led(); 
/* Issue reads to the printer while the 
write is processing. */ 
while C WriteState > 0 ) IssueRead(); 
if С WriteState < 8 ) 


EndPCom( ); 
return( Failure );); 
bffsize -= 4096; 
) bffptr += 4096; 
д 


returnC Success ); 


/*NoPrinter: Called if communications with printer can't 
be established.*/ 
NoPr inter) 


PapUnload(); 

DisposeWindowC PrintWinPtr 2; 

sprintf( &MessageBuff, Sorry, the printer “$s?” is not 
currently available., &LaserNameBuff 2); 

CtoPstr( &MessageBuff 2; 

SimpleAlert( &MessageBuff 2; 

return( Failure 2;); 

/*PAP glue routines: 

The routines stert with а SUB command that makes room for 
the result on the stack. Then they push the appropriate PAP 
globals (allocated above) onto the stack, end jump to the 
routine’s entry point, which is at some small offset from the 
beginning of pap. When they return from the call, they pop the 
result off the stack and put it into retval, which is ге- 
turned. */ 

ce 


int retval; 

esn( 

SUBQ.L 82,АТ7 

PEA ConnectId 
MOVE.L — LeserNeme,-CA7) 
MOVE.W  FlowQuantum, -CA7) 
PEA LeserStatus 

PEA OpenState 
MOVE.L papaddr, Ad 

JSR 0(А0) 

MOVE.W — CAD *,retval) 
returnC retval 2; 


eee 

int retval; 

esn( 

SUBQ.L — *2,A7 
MOVE.W — ConnectId,- CAT) 
PEA ReadSpace 
PEA ReadSize 
PEA ReadEof 
РЕА Readstate 
MOVE.L papaddr, Ad 
JSR 4(А0) 
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MOVE.N (A7)+,retval) 
return( retval ); 


one 


int retval; 

asm ( 

SUBQ.L #2,АТ 

MOVE.W ConnectId,-CA7) 
MOVE.L  WriteBuffer,-CAT) 
MOVE.W WriteSize,-CA7) 
MOVE.W WriteEof,-CA7) 


PEA WriteState 
MOVE.L papaddr , Ad 
JSR 8C AB) 


MOVE.W CA7)+,retval} 
return( retval ); 


PapS tatus.) 
int retval; 


SUBQ.L #2,AT 

MOVE.L LaserName,-CA7) 
PEA LaserStatus 

PEA LaserNode 
MOVE.L papaddr, Ad 

JSR 12(А0) 

MOVE.W — (AD*,retval) 
returnC retval 2; 


айа 


int retval; 

esn 

SUBQ.L #2,АТ 

MOVE.W — ConnectId, -CAT) 
MOVE.L papaddr, Ad 

JSR 16CA2) 

MOVE.W CA7)+,retval 


return( retval ); 
Cones 


int retval; 

asn( 

SUBQ.L %2,А7 
MOVE.L — papaddr,A2 
JSR 20(А0) 
MOVE.W (AT)+,retval 
return( retval ); 


) 
END OF DOWNLOADER SOURCE 
Resource text for RMaker: 
Tupe DITL 

‚ 20963 


* | 

BtnItem Enabled 
80 62 102 134 
Ok 


ж 2 

StatText Enabled 
10 62 65 363 

“0 


Туре МЕТ 
‚ 1000 
18 65 189 446 
20963 
5555 


мч! 


«ақы» 
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C Workshop 


Smart Documents 


Forked Tongue Programming: 
Data Forks, Resource Juggling, and Stand Alone 
Documents 

Most developers are quick to realize that a Macintosh file, 
whether application or not, could easily be an advertisement for 
Double Mint Gum. Yes, it’s two, two, two files in one. As "Inside 
Macintosh" is quick to point out, “Every file has a resource fork 
anda data fork (eitherof which may be empty). The resource fork 
of an application contains not only the resources used by the 
application but also the application code itself. The data fork of 
an application can contain anything an application wants to store 
there” Big deal. Even most novices know that when ап 
application creates a document, it places the data into the data 
fork of a file. Pretty basic stuff, even a bit dull and boring for most 
MacTutor readers. 

Butlet's step beyond the obvious for a moment, and concen- 
trate on the quote “сап contain anything an application wants to 
store there." If wecan put anything in there, how about data that 
only the application could access. No reading in other files, but 
just operating on the information found within its data fork. 
Think of itas a stand alone document. Perhaps a word processor 
that generates a file when double clicked will run itself. Ora chart 
program that makes files you could modem to a business associ- 
ate without him needing the creator application. Something a 
little like "Glue," where you have the ability to view an 
application's output without needing the application. Runtime 
versions of data bases incorporate these features. Even Microsoft 
is rumored to be considering a version of “Excel” that will create 
stand alone spreadsheets. 

Pretty neat stuff, but probably too tricky for the average 
programmer, right? Wrong. The secret lies within effectively 
using the resource and data forks. 

Stand Alone Document Theory 

The reasons for developing such stand alone documents are 
quite obvious; the ability to disseminate information without the 
need of a "mother" application to access it; being able to address 
larger audiences with your output since not everyone needs the 
creator; not needing sophisticated knowledge of an application to 
use the information found іп a document. All of these points and 
more make it worthwhile to consider incorporating the ability to 
generate stand alone documents in your applications. 

In thinking about such a project, there are several things to 
consider. The firstis the functionality you want the document to 
have. More than likely you're not going to want the stand alone 
file to do everything the original application does. Therefore, 
you'll need to include some secondary code that will simply 
display, scroll, print, or do whatever. 

But where does one put the code and resources actually 
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needed to run the document? If there is one set of CODE 
resources that run the main application and another set that will 
run the stand alone document, won't they conflict and cause 
problems? Two theories can be used in developing stand alone 
document generators. The first espouses putting all the required 
resources into a template file. The generator then simply copies 
the template, gives the copied file a new name, and inserts the 
desired information into the data fork. This is the technique used 
іп the stand alone text generator “Таке A Letter." The second 
method is cleaner, eliminating the need for template files. The 
generator program actually contains the code needed to run a 
stand alone document, although it may masquerade as another 
resource. The generator creates a new file, copies in the re- 
Sources, renames them, fills the data fork, and sets the file's 
attributes to be an application. 
Stand Alone Document Practice 

Enough theory, and on to the practice. What will be 
demonstrated is how to construct a stand alone document genera- 
tor that works with MacPaint format documents. Three sources 
are included here. The first (PaintDisplay.c) is code for a 
program that loads a Paint file stored in its data fork and then 
shows the upper left hard corner of the bit mapped image. The 
second listing (PostCard.c) is for an application called PostCard 
that builds a stand alone Paint document. (The code from 
PaintDisplay will be inserted into this document generator.) And 
finally, PostCard.r is the RMaker file. Although the sources are 
in Lightspeed C, the techniques should be general enough to 
apply to a different variation of C or even another language. 
(Lightspeed info: Both projects (PaintDisplay proj and PostCard 
proj) should include MacTraps plus their own respective source 
files and be set to build applications. PostCard's creator type 
should be ‘PCRD’.) 

The first step is to compile PaintDisplay.c. This source 
contains a standard algorithm for displaying an image from a 
MacPaint format file. It initializes everything, opens up its data 
fork, grabs bytes, puts up a window, displays the left corner of the 
Paint document, and waits for a mouse click to quit. All in one 
breath. Don't try to run it quite yet though. If you do, it will be 
looking in its own data fork for something that isn't there yet, and 
your curiosity will be rewarded with a bomb. 

The only real item in the code that needs discussing, is how 


one goes about accessing the data fork. To quote from the source: 
if CGetVolC&thisVolume, &vRef ) != noErr) 
ErrorRoutineCFALSE, 0); 
GetAppParms(& thisProgram, &temp, &thisHandle); 
if CFSOpen( thisProgram, vRef ,&srcFile) != noErr) 
ErrorRoutineC TRUE, srcF ile); 


The first step is to determine what volume the application is 
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оп with а GetVol( call. Next, use GetAppParms( to return the 
name of the current application. Now pass the application's 
name and the volume reference number to FSOpen(). It will 
oblige by opening up your application's data fork. 

Resource Rascality 

Once you've compiled PaintDisplay, the next task is to use 
RMaker on the PostCard.r file. This file contains the resources 
for the menus, dialogs, bundles, icons, etc. for the PostCard 
application. It also has the necessary resources to be used in 
creating the stand alone document. 

Anoften overlooked feature of RMaker is the ability to copy 
specific resources from one file to another during the compile 
stage. By using the “.Е” command you could load, let's say, a 
font from an existing file into the resource file you're currently 
compiling. The format is: 


Type FONT - GNRL* the new resource type (FONT) 
8 * the new resource ID 

«R * the RMaker directive 

Fonts FONT 12* the file “Fonts?” and the resource 


ж (FONT 12) to copy into the new resource 


RMaker is pretty lax as to letting you get away with things 
in certain areas. This feature proves beneficial when building 
program generating applications. Ав mentioned before, the 
biggest problem in writing an application that builds another, is 
where to stick the code that will be spawned off. Obviously you 
can't have a program with two CODE 0 resources, at least 
without the potential for serious problems. 

The solution is to build a new resource type of your choos- 
ing, and then through RMaker, stuff the CODE into it. For 


example: 
Туре РАКЕ = GNRL % creates a resource type called FAKE... 
,@ ж with en ID of 0 


.R ж tells RMaker to load in something 
SuperEdit CODE 0 * else, i.e., the jump table from 


х а file called “SuperEdit” 


This is what's happening іп PostCard.r. The previously 
compiled code from PaintDisplay is being read in, and then 
assigned a new type and identification. The CODE resource is 
still the same, but it’s gone into hiding by changing its name. It’s 
as easy as that. When the resource file is compiled, you'll have 
your CODE just sitting there, ready to use, but disguised as 
something else that won’t conflict with the the program that will 
be using it to create another application. 

Taking a peek with ResEdit at the results. FAKE and 
DUMY are really code resources, but with their new identities, 
don’t conflict with code resources found in the application that 
will use them. 

Two words of advice on using RMaker in such a fashion. 
The first is, RMaker frowns on using a source file with a space in 
its name. Therefore, “My File” will cause you problems but 
“MyFile” will not. The second caveat is to be aware of path 
names. If all of your formats look all right, but RMaker still is 
complaining, odds are you have an improperly laid out path. 
Double check it. 

You’ll notice in the PostCard.r file, more than just CODE 
resources are being changed. Remember, all compilers are not 
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Fig. 1 Using ResEdit to see our fake code resources 


created equal. Some will generate just two code segments (for 
under 32k of code, of course): 0 - the jump table, and 1 - the actual 
code. Others, Lightspeed C for example, will generate more than 
two code segments and a variety of other resource types where 
data is stored. That's what all the CRELs, DATAs, ZEROS, etc. 
are all about. When you are transferring and converting code 
resources, be sure you get everything your particular compiler 
needs for the application to run. At first put everything in, but 
after a while try some experimenting. At times you'll find you 
don't need all of the data and support resources. 
Resource Moving Without ResEdit 

The last step in the process is to compile PostCard.c. The 
compiled resources from PostCard proj.Rsrc are copied in, and 
the application is ready to run. 

From the Macintosh's perspective, here's what happens 
when the user selects "Make a PostCard..." from the menu: 

The SFPut() routine is called to select a name and location 
for the new file. CreateResFile() is used to create the nàmed file. 
Finder attributes are then set, and the resource fork of the new file 
is opened. 

Now the fun stuff. The code determines what the resource 
reference number of the current application is (in this case 
PostCard). It then makes use of a programmer defined function 
called ResTransfer(). 

ResTrensfer(sourceRes, sourceID, destRes, destID) 


КезТуре sourceRes, destRes; 
int sourceID, destID; 


Handle — codeHandle; 
codeHandle = NewHandle(C9); 
codeHandle = GetResource(sourceRes, source ID); 
UseResF i leCresRef ); 
De tachResource(codeHand le); 
AddResource(codeHandle, destRes, destID, “\p”); 
if (ВезЕггог() != noErr) ( 
DoMessage(“\pSorry, couldn’t copy the required re- 
source.” ); 
myError = 1; 


) 
ResTransfer() is passed the resource type and ID of the 
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resource to be copied, along with what type of resource and what 
ID number you want the copy to appear as. GetResource() is used 
to get a handle to the resource to be copied. UseResFile() is then 
called with the resource reference file number of the application 
that will be created. This tells the resource manager to only deal 
with the resource fork of the new stand alone document. 

As per "Inside Macintosh," the resource to be copied is 
detached, and then added to the new application with AddRe- 
source(). AddResource() is passed the handle to the resource, 
along with information concerning type and identification. If for 
some reason it can’t be added, an error handling routine is alerted. 

ResTransfer() is called repeatedly for all of the resources 
needed to be placed in the stand alone document. Atfirst BNDL, 
FREF, ICN#, etc. are moved in, giving the application its own 
unique type and icon. Next the FAKE and DUMY resources are 
copied and then converted back to their original types and IDs. 

Once all the resources have been moved and/or changed, 
UpdateResFile() is used to tell the resource manager the new file 
needs updating, effectively adding and writing all of the re- 
Sources. The stand alone document's resource fork is then 
closed, and UseResFile() is called to revert the current resource 
fork back to PostCard. 

With the resources in place, SFGet() is called to select the 
Paint format file to be read in. Its data fork is read and then written 
to the stand alone document's data fork. With no errors reported, 
the stand alone document has now been created and is ready to 
run! 

| Final Thoughts 

Needless to say, PostCard ain't very fancy. If one was to do 
it right, scrolling, desk accessory support, more error handling, 
perhaps even printing and the ability to save a full MacPaint 
format document out of it should be included in the PaintDisplay 
code. Did I just hear the basis for a shareware product? 

Also keep in mind that PostCard just demonstrates the idea 
of stand alone documents. Although application generators like 
it are useful, stand alone documents would really be best created 
by say a"WriteNow" or “SuperPaint.” Ideally, the entire process 
would be incorporated as a function in an actual, full blown 
program where the user would simply select a menu item to 
create the stand alone file. 

One potential argument to the idea of stand alone documents 
is more code overhead in the original program. However, with 
a little thought and planning this can easily be avoided by 
segmenting the program so the main application and the one to 
be generated would share some common code. Even if an extra 
15 or 20k went into the final product, users would likely justify 
the size increase because of the benefits. 

As you can see, creating stand alone documents isn’t that 
difficult. The problems with data and resources can easily be 
overcome, with the end result being things like self running 
documentation, double clickable desktop presentations, or stand 
alone spreadsheets. Hopefully in the near future we'll be seeing 
more of stand alone documents. But for now, why don’t you give 
your own а try. 

/* 
* PostCerd, version 1.0, Lightspeed C 
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* demonstrates using data forks end resource tricks 


x Соруг1 


ght 1987 by Joel McNemara - A11 Rights Reserved 


* for MacTutor Magazine 
* initial coding - October 12, 1987 


include 
t include 
include 
include 
"include 
include 


“MacTypes.h” 
“QuickDraw.h” 
“WindowMgr .h” 
“EventMgr .h^ 
*MenuMgr .h^ 
*FileMgr.h^ 
“MemoryMor .h^ 
*ResourceMgr . h^ 
*StdF ilePkg.h^ 
*0SUt i1.h^ 
"DialogMgr.h^ 


/* defines... */ 
"define MessageDLOG 255 


"def ine AboutDL0G256 
"def ine HelpDLOG 257 
#def ine AppleMENU1 
#define About 1 
8def ine FileMENU 255 
"define Quit 1 
#def ine CommandMENU 256 
"дег ine MakeCard 1 
#def ine Help 3 
/* globals... */ 
Boolean done; 
char theS tring[256]; 
MenuHandle ^ AppleMenuHndl, FileMenuHndl, CommandMenuHnd!; 
EventRecord — theEvent; 
DielogPtr theDialog; 
int resRef , dummy, nyError ; 
/* main */ 
nainC) 
( 

InitializeC); 

do( 

MainLoop(); 


}whileC! done); 


/* as always... */ 


Initializ 


eC) 


InitGraf(&thePor t); 
InitFonts(); 

InitWindows(); 

InitMenusC); 

TEInitC; 

InitDialogs(0); 
InitCursor(); 
FlushEvents(everyEvent, 0); 
Se tUpMenus( ); 


done 


= FALSE; 


myError = 0; 


) 


/* make the menus */ 
[uM 


AppleMenuHnd] = GetMenuCAppleMENU); 
AddResMenuCAppleMenuHndl, ‘DRVR’); 
Inser tMenuCAppleMenuHndl, 0); 

Fi leMenuHnd] = GetMenu(CF i leMENU); 

Inser tMenu(F i leMenuHndl, 0); 
CommandMenuHndl = GetMenuCCommandMENU); 
Inser tMenuCCommandMenuHndl, 0); 
DrawMenuBar (); 


/* generic dialog displayer */ 
DoD ialog¢ theDLOG) 
ү іһе0і 06; 


theDialog = GetNewDialog(theDLOG, 0, -1); 
DoButton( theDialog); 

ModalDialog(8, &dummy); 
DisposDialog(theDialog); 


/* message display routine */ 
DoMessage( theMessage 2 

Str255 іһеМеѕѕаде; 

( 


theDialog = GetNewDialog(MessageDLOG, 0, -1); 
ParamText(theMessage, "\р”, "Mp", "\р”); 
DoButton( theDialog); 

ModalDialog(O, &dummy); 
DisposDialogCtheDialog); 


/* loop until we're done */ 
бады 


SystenTask(); 
if (GetNextEventCeveryEvent,&theEvent)) ( 
switch CtheEvent.what) ( 
case mouseDown: 
DoMouseDownt 2; 
break; 
defeult: 
break; 


) 


/* if we have а mouse down */ 
DoMouseDown( ) 


WindowPtrwhichWindow; 
int thePart; 
thePart = FindWindowCtheEvent . where, &whichWindow); 
switch(thePart) ( 
сазе inMenuBar : 
DoMenu( 2; 
break; 
case inSysWindow: 
SystemClickC&theEvent, whichWindow); 
break; 
default: 
break; 
) 
) 
/* if a menu hit then... */ 
"oben 


long menuChoice; 
menuChoice = MenuSelect(CtheEvent . where); 
DoMenuItem(menuCho ice ); 


/* which menu was selected? */ 
DoMenuI temCmenuCho ice?) 
long menuChoice; 


int  theMenu, theItem; 
if (menuChoice != Ø ) ( 
theItem = menuChoice; 
theMenu = (menuChoice ›› 16); 
switch CtheMenu) ( 
case AppleMENU: 
DoDACtheItem); 
break; 
case FileMENU: 
done = TRUE; 
break; 
case CommandMENU: 


96 


) 


DoCommands( {Ле tem); 
default: 
break; 


) 
HiliteMenuC0); 


/* the apple menu was hit */ 
DoDAC {Ре tem) 


int 


int 


{Пе tem; 


accNumber ; 

if CtheItem == About) 
DoDialogCAboutDL0G); 

else ( 
GetItenCAppleMenuHndl, theItem, theString); 
accNumber = OpenDeskAcc(theString); 


/* the commands menu was hit */ 
DoCommands( the! tem) 


int 
( 


(һе tem; 


switch(theItem) ( 
case MakeCard: 


Conver tFileC); 
break; 
case Help: 
DoDialogCHe1pDLOG); 
break; 
default: 
break; 
) 
/* make а postcard */ 
Coe 
char* buffer; 
long theE0F; 
int currentResRef ,ref Num, destRef ; 
Handle codeHandle; 
Point myPoint; 
SFReply peintReply, myReply; 
SFTypeList X myTypes; 
FInfo myF Info; 
05Егг myErr; 


т/Турев(01 = ‘PNTG’; 

myPoint.h = 90; 

myPoint.v = 90; 

/* first we create the application */ 
DoMessage(“\pFirst name the PostCard you want to cre- 


ate.”); 


 SFPutFileCmyPoint, “\pEnter PostCard name:^, “\pMy 


PostCerd^, 0, 


&myReply); 
( (nyReply.good) 


SetVolCO, myReply.vRefNum); 
CreateResF i leCnyReply. f Name); 
/* meke it what we want... */ 
myFInfo.fdType = ‘APPL’; 
myFInfo.fdCreator = ‘PDIS’; 
myFInfo.fdFlags = fHesBundle; 
nyFInfo.fdLocation.h = 0; 
myFInfo.fdLocation.v = 0; 


SetFInfo(muReplu.fName, myReply.vRefNum, &myFInfo); 


/* open its resource fork */ 
resRef = OpenResF ileCmyRep ly. fName ); 
if CresRef != -1) 


/* get PostCard’s resource ref number and then 


start moving the resources */ 
currentResRef = CurResFile(); 
/* first the obvious ones */ 
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ResTrensferC'BNDL^, 129, ‘BNDL’, 128); 
ResTransferC “Р015”,0, 'PDIS^,0); 
ResTrensfer( “ҒКЕҒ”, 128, 'FREF ^, 128); 
ResTrensfer( ' ICN't^ , 129, ^ ICN' ^, 128); 
/* now grab the FAKEs and make them CODE */ 
ResTransfer('FAKE",0, "CODE ^, 0); 
ResTransfer( ‘FAKE’, 1, CODE", 1); 
ResTransfer( ‘FAKE’ ,2, ’CODE’,2); 
/* finally get the DUMYs and convert them */ 
ResTransfer( 'DUMY ^ ,0, ’CREL’,2); 
ResTransf er 'DUMY' , 1, DATA ,0); 
ResTransfer( ^DUMY ^ ,2, "DREL ^,0); 
ResTransf er C 'DUMY ^, 3, 'STRS ^,0); 
ResTransfer( 'DUMY ^ 4, 'ZERO^,0); 
/* updete the new application, close it, make PostCard 
the current open resource fork */ 
UpdateResF ileCresRef ); 
CloseResF i leCresRef ); 
UseResF ileCcurrentResRef ); 
/* see if we have апу errors - open the application */ 
if С CFSOpenCmyReply.fName, myReply.vRefNum, 
&destRef) != noErr) || (muError == 1) ) ( 
ОоМеззаде("\р5оггу a resource error 
prevented the PostCard from being created. ^); 
FSDeleteCmyReply.fName, myReply.vRef Num); 
myError = 0; 


else 


/* here we select the paint file we want to convert */ 

ОоМеѕѕадеС“\р№ож select the Paint file you 
want to display.”); 

SFGetFileCmyPoint, “\p”, Ø, 1, myTypes, 0, 
&paintReply); 

CpaintRep ly. good) 


/* open, read, and write into the document */ 
if CFSOpen(paintReply.fName, paintReply.vRefNum, &refNum) == 
noErr 2 


( 
if С GetEOFCrefNum, &theEOF) != noErr) 
myError = 1; 
buffer = NewPtrCtheEOF); 
if € FSRead(refNum, &theEOF, buffer) != noErr) 
myError - 1; 
if € FSWriteCdestRef, &theEOF, buffer) != noErr) 
myError = 1; 
myErr = FSClose(refNum); 
myErr = FSClose(CdestRef ); 
if CmyError != 1) 
DoMessage(“\pYour PostCard has been 
created! ^); 


) 
) 
else 
/* get rid of file we've created */ 
FSDeleteCnyReply.fName,myReply. vRef Num); 
) 
) 
else 
myError = 1; 


if CmyError == 1) { 
/* opps, problems - blitz the file */ 
DoMessage(*\pSorry an error prevented the PostCard 
from being created.^); 
FSDeleteCmyReply.fName ,myReply.vRefNum);) 


/* grab а resource and rename it routine */ 
ResTransferCsourceRes, sourceID, destRes, destID) 
ResType sourceRes, destRes; 

int sourceID, destID; 
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( 
Handle — codeHandle; 
codeHandle = NewHandle(0); 
/* get the source resource */ 
codeHandle = GetResource(sourceRes, sourceID); 
/* set the current res file to the stand alone document */ 
UseResF i leCresRef 5; 
/* detach the source resource... */ 
DetachResourceCcodeHandle); 
/* and add it to the document */ 
AddResource(codeHandle, destRes, destID, “\р^); 
if (ResErrorC) != noErr) ( 
DoMessage(“\pSorry, couldn't copy the required 
resource .^); 
myError = 1; 


) 

/* fancy button for the modals */ 
DoBut ton(myDialog) 
шна. 


short nyTupe; 

Handle myHandle; 

Rect nyBox; 

GrafPtr dummgPort; 
GetPortC&dumnyPor t); 
SetPortCmyDialog); 

GetDItemC myDialog, 1, &myType, &myHandle, &myBox ); 
InsetRect(&myBox, -4, -4); 

PenSize(3, 3); 

FrameRoundRect(&myBox, 16, 16); 

PenNormal(); 

SetPortCdummgPor t); 


/* 
* PaintDisplay.c 
* This supplies the code needed for PostCard application 
* to generate а stand alone Paint file. 
* copyright 1987, Joel McNamara - All Rights Reserved 
* for MacTutor Magazine 
initial coding - October 12, 1987 
в) 


8include «MacTypes.h? 
"include <QuickDraw.h> 
®include <WindowMgr .h» 
8include <EventMgr .h> 
8include <MemoryMgr .h> 
8include <SegmentLdr .h» 
/* setup world, display the image, and wait for a click */ 
nainC) 
InitGraf (&thePor t); 
InitFonts(); 
InitWindows(); 
InitMenus(); 
TEInitC); 
InitDialogs(@L); 
InitCursor(); 
FlushEvents(everyEvent, 0); 
displayPaint(); 
while (!Button()); 


* 


) 
/* the guts of the paint display progrem */ 
о 


сһаг *srcPtr, *dstPtr, *saveDstPtr, *skipPtr; 
int srcFile, scanLine, vRef, temp; 

long srcSize, paintSize; 

517255 thisProgram; 

StringPtrthisVolume; 

GrafPort aPort; 

BitMap theBitMap; 

Rect muRect; 

WindowPtrmuWind; 

Handle thisHandle; 
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/* ме’11 be sloppy with the nonrelocatable pointers and 


let them 811 get cleaned up upon exiting */ 


/* the first 512 header bytes to skip */ 
srcSize = 512; 
skipPtr = NewPtr(5 12); 
if CsrcPtr == OL) 
ErrorRoutineCFALSE, 8); 
/* the biggest it can be */ 
srcPtr = NewPtr(5 1840); 
if (srcPtr == ØL) 
ErrorRoutineCFALSE, ø); 
/* see who and where we аге... */ 
if CGetVolC&thisVolume,&vRef) != поЕгг) 
ErrorRout ineCFALSE ,2); 
GetAppParms(&thisProgram, &temp, &thisHandle); 


/* then open our data fork and read past the header */ 


if K«FSOpenCthisProgrem, vRef ,&srcFile) != noErr) 
ErrorRout ineC TRUE, srcFile); 

if (FSRead(srcFile,&srcSize,skipPtr) != noErr) 
ErrorRoutineC TRUE, srcF ile); 

/* see how big we really are... */ 

if CGetEOFCsrcFile,&paintSize) != noErr) 
ErrorRoutineC TRUE, srcF ile); 

paintSize -= 512; 

/* now read the rest of the bytes and close */ 

if (FSRead(srcFile, &paintSize,srcPtr) |= noErr) 
ErrorRoutine( TRUE, srcF ile); 

if CFSClose€srcFile) != noErr) 
ErrorRoutineC TRUE, srcFile); 

/* get а destination pointer... */ 

dstPtr = NewPtr(5 1840); 

if CdstPtr == OL) 
ErrorRoutineCFALSE, 8); 

saveDstPtr = dstPtr; 

scanLine = 1; 

/* and start unpacking the compressed Paint data */ 

for C(scenLine = 1; scanLine <= 720; scenLine**) 
UnpackBits(&srcPtr,&dstPtr, 72); 

/* make а window */ 

SetRectC&myRect, 12,35,500,325); 

myWind = NewWindowCOL , &myRect, “Ар”, TRUE, 1,- 


1L, FALSE, 99); 


/* configure our bitmap */ 
theBitMap.baseAddr = saveDstPtr; 
theBitMap.rowBytes = 72; 
theBitMap.bounds. (ор = 0; 
theBitMap.bounds. left = 0; 
theBitMap.bounds bottom = 72 * 8; 
theBitMap.bounds.right = 720; 
/* and copy the Paint bits into our window */ 
CopyBitsC&theBitMap, &myWind->»portBits, &myWind- 


yportRect, &myWind->»portRect, srcCopy, ØL); ) 
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/* simple no frills, beep and quit */ 
ErrorRoutineC closeFile, fileNum 2 
Boolean closeFile; 
int f ileNunm; 
( SusBeep(5); 

if CcloseFile) 

FSCloseCf ileNum); 
ExitToShe11C2; 


* resource file for PostCard.c 

* by Joel McNamare 

* for MacTutor Magazine 

* October 12, 1987 

Development:MacTutor:PostCard proj.Rsrc 

* you’11 probably want to change the pathname 

* the bundles, first for PostCard then PaintDispley 


FREF 
0 128 


ж this BNDL will be renumbered by the application 


* PostCard file type 
Type PCRD = STR 


‚0 
PostCard Version 1.0 - 12 Oct 87 


х PaintDISplay file type 
Type PDIS = STR 
0 


PaintDisplay Version 1.0 - 12 Oct 87 


* der menu 
Type MENU 
1 


\14 
About PostCerd... 
(- 


,255 
File 
Quit 


,256 

Commands 

Make а PostCard... 
(- 

Help... 


* the dialog items 
Type DITL 

‚255 (4) 

2 


button 
48 272 66 349 
OK 


staticText Disabled 
6 11 43 358 
“0 


‚256 (4) 

5 

button 

171 86 190 178 
OK 


staticText Disabled 
2 86 20 177 
PostCard 1.0 


staticText Disabled 
24 13 87 263 
PostCard creates an application and then places a Paint 


file into the data fork, thus creating a stand alone viewer. 


staticText Disabled 
124 24 158 241 


Copyright 1987, Joel МсМапага(00 All Rights 
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Reserved 


steticText Disabled 
100 50 118 208 
for MacTutor Magazine 


,251 (4) 

4 

button 

166 295 184 406 
OK 


steticText Disabled 

3 4 38 423 

PostCard takes а MacPaint document and turns it into a 
stand alone application that displays the upper left corner. 


staticText Disabled 

42 4 91 423 

When the Paint document is selected a new file is created 
with CODE resources (РАКЕ апа DUMY - stored within the 
PostCard application) copied and renamed into the new file. 


staticText Disabled 

95 4 161 423 

These resources drive the new application by reading its 
own data fork (copied in from the Paint file) and then 
displaying the bit mapped image. 


* the dialogs 
Туре DLOG 

,255 (4) 

message 

60 68 136 438 
Visible NoGoAway 
1 

0 

255 


,256 (4) 

about 

52 122 252 394 
Visible NoGoAway 
1 


0 
256 


‚251 (4) 

һе1р 

46 48 242 414 
Visible NoGoAwau 
1 

0 

257 


* here's the trickery - we create new resources of type 
FAKE, and read 

* the CODE resources from PaintDisplay into them. 

Туре FAKE = GNRL 


М 


R 
Development:MacTutor:PaeintDisplay CODE 0 
х 0,711 need to specify a different pathname above 


‚1 

.R 

Development:MacTutor:PaintDisplau CODE 1 

Ж you'1] need to specify а different pathname above 


,2 
AR 
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Development :MacTutor :PaintDisplay CODE 2 
* you'll need to specify a different pathname above 


* now get the rest of the resources we need (as required 


by Lightspeed С) - 
* creating dummy resources named DUMY. 
Туре DUMY - GNRL 
д 
R 
Development:MacTutor:PaintDisplay CREL 2 
x 09711 need to specify a different pathname above 


‚1 

‚К 

Development:MacTutor:PaintDisplay DATA 0 

х you'll need to specify а different pathname above 


,2 
R 


Development:MacTutor:PaintDispley DREL 0 
* you’ll need to specify a different pathname above 


‚3 

R 

Deve lopment :MacTutor :PaintDisplay STRS 0 

* you^1] need to specify a different pathname above 


‚4 

R 

Deve lopment :MacTutor :PaintDisplay ZERO Ø 

* you^1] need to specify a different pathname above 


* now the application icon 

Type ICN* = GNRL 

, 128 

.H 

00000000 00000000 1FFFF800 20003С00 
20007C00 2ТҒҒҒС00 2401ҒС00 2553FC00 
2402F400 2545E400 24090400 25428400 
24010400 25420400 24003F00 25084080 
24108040 23F 13020 20396814 20 1ETF8F 
20023007 261F0007 26008007 20006007 
3FFFFFE7 2000021Ғ 1FFFFCO7 00000000 
00000000 00000000 00000000 00000000 
* next the mask 

00000000 00000000 ІҒҒҒҒ80д2 3FFFFCOO 
3FFFFCOQ ЗҒҒҒҒС00 ЗҒҒҒҒС00 ЗЕҒҒҒС00 
JFFFFCOQ ЗҒҒҒҒС00 3FFFFC00 ЭҒҒҒҒС00 
JFFFFCOQ 3FFFFCOQ 3FFFFF00 3FFFFF80 
OFFFFFC® 3FFFFFE@ SFFFFFF4 SFFFFFFF 
SFFFFFFF 3FFFFFFF SFFFFFFF SFFFFFFF 
SFFFFFFF ЭҒҒЕҒЕІҒ 1FFFFCO7 00000000 
00000000 00000000 00000000 00000000 


* now the stand alone file’s icon 
,129 

00000000 00000000 00000000 00000000 
00000000 00000000 00000000 00000000 
00000000 FFFFFFFF 8 100000 1 8 10000Ғ0 
81Ғ000А0 81100005 811000AD 81100005 
811000FD 81100001 80Е0000 1 81Ғ0000 1 
81700001 81Ғ80001 81F80001 B1E85FFF 
81F80BFF 80003ҒҒҒ 80ҒФОҒҒҒҒ 80703ҒҒҒ 
8019FFFF 80000001 FFFFFFFF 00000000 
* next the mask 

00000000 00000000 00000000 00000000 
00000000 00000000 00000000 00000000 
00000000 FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF 00000000 
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С Workshop 


А Background Task for Measuring Load 


Peter Kornisafull time software quality assurance engineer 
for Apple Computer, and a full time undergraduate student in 
Mathematics at UC Berkely, which makes him a busy young man! 
In this article, he gives us a technique for measuring the activity 
under multifinder by timing null events in a background task. 


Тгиетм Multitasking 


I don't have to tell you that multitasking is good. By not 
having to wait on the computer to finish a task before you can go 
on to the next one you save time, frustration, and creative 
energies. There's nothing as frustrating to me as having an idea 
and wanting to take it somewhere but not being able to do so 
because my computer is busy printing, or downloading, or 
compiling (admittedly with LightSpeed C my wait isn't very 
long). Butonce we have the concept of multitasking, is multifin- 
der True™ multitasking? Before I tackle that one, I want to give 
a brief history... 

In the beginning there was the Macintosh (128K model). 
With it I could have a Desk Accessory or three pop up whenever 
I had an idea that I didn't want to interrupt whatever else I was 
doing to work on. And, if I hadn't foolishly started a print job or 
an {up,down} loading session on my modem, I was fine. Some 
of the usefulness of multitasking already! 

When the 512K Mac came along there was more RAM to 
play with, and some programs took advantage of this RAM to use 
the Vertical Retrace Manager for more than just a cursor blinker 
and tick counter. With programs like SuperSpool, I could bring 
upaDA even while my program was printing. And the DAs were 
getting bigger too. There were spreadsheets, filers, outliners and 
word processors and terminal programs (even one called Back- 
down, that would download for me in the background). And 
while all of this took even more RAM, the Mac Plus was released 
shortly and life was pretty ok. 

Except that for a program to allow itself to be run “in the 
background', it had to go through a series of contortions, and 
deny itself use of the Memory Manager, and so very few 
programs were written this way. Certainly Backdown, while 
nice, wasn't a full-blown terminal emulator. And still there was 
no way of checking spelling in the background, or compiling, or 
recalculating a spreadsheet, or what-have-you. The Vertical 
Retrace Manager just wasn't cut out to be a scheduler. 

Even with Switcher I still couldn't do all these sorts of things 
at once; I could only switch between them when they were idle. 
And this I had to do by hand (with the exception of ThunderScan, 
but there's no surprise there, as it shares authors with Switcher). 
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Peter Korn 
Apple Computer 
МасТшог Vol. 4 No. 3 


ш 


GLA appl 


Edit Configure 
Untitled 


Fig. 1Our little Load Average Window — 
Measures time between null events 


A True™ multitasking system should allow me to run 
True™ tasks, and have them all going simultaneously (or close 
to simultaneously—you know what I mean). But an important 
question is, must this be preemptive? As a user, do I really care 
how it's all done, so long as my download, spreadsheet recalcu- 
lation, and mandelbrot plot all continue whilst I'm busy writing 
a letter to grandma? In fact, if Pm typing my letter, I don't want 
the computer to be any slower responding to my keystrokes just 
because it's doing other things—I’m being creative here, and I 
don't want to have to deal with a sluggish interface that slows те 
down just because I have the computer doing other things as well. 

In wider circles, True™ multitasking is considered preemp- 
tive multitasking. Each task (program, driver, what-have-you) is 
assigned some priority number (-10 to 10, say), and some 
scheduler program arbitrates which task gets how much CPU 
time when. Firstitlooks at all the programs of the highest priority 
level, and for all of those that want time (some may not; perhaps 
their waiting for slow networking i/o, or are finished computing 
their mandelbrot and haven’t been given further instructions), it 
allocates that time evenly amongst them, interrupting each at 
some small, regular interval (100 milliseconds, say), and giving 
time over to the next needy task of equal priority level. When no 
tasks at that priority level want time, then the scheduler looks at 
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tasks of a lower priority level and parcels ош time as before to all 
of them, and so on. If the user doesn't want his creativity 
disrupted, he merely sets the priority of the task he is working on 
to something higher than all the other tasks. And in between 
keystrokes (in the word processor, say), the other tasks will get 
time to do what they need to do (ie: when the user is idle [for some 
fraction of a second]). 

Apple, in it's infinite wisdom, didn't do it this way. The 
main reason was for compatibility. Another was because of 
system architecture (while the Amiga can carry it off without a 
hardware Memory Management Unit that ensures that whatever 
memory address a program writes to isn't taken by something 
else, certain developers [including Apple] have too long thought 
of the Macintosh as belonging entirely to the program currently 
running [allowing for those piddling desk accessories, maybe] to 
pull this off). But is Apple's way also True™ multitasking? 
Well, if it gets the job done... 


Multitasking the Macintosh way 


Under the new operating system (System Disk 5.0, which 
contains System 4.2, Finder 6.0, MultiFinder 1.0, Chooser and 
Control Panel 3.2, and [aha, so this is where they got the number] 
LaserWriter Driver 5.0), we can run a program called MultiFin- 
der. MultiFinder, (like Switcher and Servant before them) allows 
us to load in several programs at once, and switch between them 
at will, in a very clean fashion (click on window beneath 
belonging to another program, select the program from the Apple 
menu, or cycle through the program list on the upper right corner 
of the MenuBar; this type of program switching is what tech note 
#180 calls “Major Switching"). Additionally, programs that 
define themselves as ‘backgroundable’ can get time when the 
"foreground' program (the one who's window is foremost and 
active) is idle. 

This is done by taking control when the foreground program 
calls GetNextEvent(, EventAvail(), or WaitNextEvent(), a new 
call under multifinder, and seeing what the foreground 
program'seventis. If the event is nota nullEvent, the foreground 
program gets it. If the event is a nullEvent, then things get 
interesting and somewhat confusing. 


Null Event Processing 


If our foreground program is not MultiFinder friendly, it's 
doubtless using GetNextEvent(). In this case, MultiFinder 
doesn't do anything on the first nullEvent. Or the second 
nullEvent (this is for programs that do work on nullEvents but 
were written before the program's authors knew about MultiFin- 
der, like MS-Word). But the third nullEvent the foreground 
program never sees (in the current version of MultiFinder — in 
later versions GNE() calling apps may only see 1 nullEvent, or 
perhaps none). Instead MultiFinder looks about and sees if there 
are any background tasks running (ГИ describe those in a 
moment), and turns control over to one of them (this type of 
switching is called “Minor Switching" by tech note #180). That 


© The Definitive MacTutor, Vol. 4 


background task then calls GNE() or WNEQ, and MultiFinder 
takes over immediately, checks the event, and if it's not a 
nullEvent, returns control immediately to the foreground pro- 
gram. Ifitisanother nullEvent, MultiFinder checks to see if there 
are any other background tasks, allocating nullEvents in a round- 
robin fashion until a non-nullEvent comes along, at which time 
control is returned to the ‘foreground’ task, which is returned that 
non-nullEvent. 

For everything to work right, MultiFinder has to make 
certain assumptions. First, it assumes that all programs call 
GNE(, WNE(), or EA() regularly (which a program is under no 
obligation to do, though it would be nice...). If a program 
doesn't, then when it's in the foreground, no background tasks 
will ever get time. Furthermore, all programs that want to run as 
background tasks have to call one of these three, and call them 
pretty often, in order to ensure that the foreground task can 
quickly respond to any user event (a non-nullEvent, in this case). 
There's no more a way to stop a renegade background task from 
taking over the CPU the moment it gets it than there is a way to 
stop a renegade program from making the machine crash — 
programmers and users and the media will be the judge, not any 
hardware MMU. 

So is it True™ multitasking? You decide. 


How to be a (good) background task 


Formally all you have to do to be a background task is to have 
a Size = -1 resource with the can background bit set. As a 
background task, to do any work, you also have to check for, and 
use, nullEvents. Furthermore, the obedient background task 
does no more than 50-100 milliseconds of work before calling 
GNEQ, WNEO), or ЕА() again. for a wonderful example of а 
disobedient background task, look at Apple's PrintMonitor 
that's shipping with the 5.0 release (clearly following in 
MacWrite's lawless ways...). Caveat: in MultiFinder 1.0 there 
is abug when using GNE() from the background: you will get no 
nullEvents when you are first launched—you have to be 
switched out and then back in again before you start seeing those 
precious nullEvents. 

As a background task, you can do almost anything a fore- 
ground task can do. You can write to the screen, read from disk, 
use the memory manager, play sound, etc. You can even be a 
foreground task (like a clock that updates the time constantly, and 
in the foreground allows the user to change from 12 hour to 24 
hour display—or like a graphic load average program [which 
happens to be the subject of this article]). However... you are 
warned to do all of your work inside of windows. Drawing to the 
screen is a no-no. And if you are like a certain game I won't 
mention (but who's initials are Crystal Quest), and you don't 
draw in a window and expect the user to click the mouse button 
whilst using your game, you will swiftly find yourself being 
switched (twitched, as it's sometimes called) out while whatever 
program's window was underneath the mouse when the 
mouseDown happened suddenly coming into the foreground. 
Also you shouldn't put up a Modal Dialog box, as it won't come 
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up in the foreground but will stay in your layer and the user might 
never see it. Nor should you do anything that might affect the 
foreground task, like fiddling with the menuBar or cursor. 
Lastly, if your program is so uncouth as to change some system 
parameter (like the mouse tracking ratio, as done by a certain 
program with the same initials), you should at least be good 
enough to set it back to what it was when you get twitched out. 

Which brings us to the next level of MultiFinder compatibil- 
ity: accepting suspend/resume events (as the bit in the Size = - 
1 resource is labeled). These programs recognize two new event 
types that came about from the Switcher days: suspend and 
resume. À program (any program, not just backgroundable ones) 
that accepts suspend events doesn't ever get that first nullEvent 
(on a Major Switch), (unless it's got the background bit set, in 
which case it will share nullEvents with the other programs that 
have a background bit set). Instead it will see a suspend event. 
A suspend event is ап app4Evt (theEvent.what = 15) with bit 0 of 
theEvent.message clear. A resume event is ап app4Evt with bit 
Osetto 1. А suspend event means that the program is about to be 
juggled (for some reason the future tense is juggled, and other- 
wise it's called twitching), and the program should set the state 
of anything it muddled with back to what it was before it muddled 
with it and so forth, and then call СМЕО), WNE() ог ЕАО. 
Furthermore, if bit 1 of theEvent.message of the suspend event is 
set, the application should convert it's internal clipboard to the 
deskscrap (or vice versa if the event is a resume event) so that 
other applications can use it. If that bit is clear, then no scrap 
conversion is necessary. 

Another bit in the Size = -1 resource is the Juggler Aware bit. 
If this bit is set, the program uses WNE() instead of GNEQ) if 
MultiFinder is running (see the example in my code or in tech 
note #158 [where I stole it from] for how to do this). WNEQ has 
two additional parameters that it gets passed: sleep (an unsigned 
long), and mouseRgn (a RgnHandle). Sleep is the number of 
ticks that the application can go without getting a nullEvent (for 
things like updating a blinking cursor or clock getting a character 
from the modem or some such). mouseRgn is a RgnHandle 
within which the mouse can move and the program needn't be 
consulted as to it changing shape. Anexample of this is a terminal 
emulator, who's cursor is an I-beam when it's over the content 
region of the window, and an arrow when it's over anything else. 
NIL cast to the proper variable type can be passed for either of 
these parameters. 

Sayeth Apple: you shouldn't set the Juggler Aware bit 
unless you use WNEQ, and recognize suspend/resume events, 
and are in all ways cognizant of MultiFinder and running with 
other foreground and background tasks. And what does this 
involve? 

Background tasking programs (in fact, all programs) should 
now do a number of things in order to better function in the 
MultiFinder environment. Programs should not do any work on 
updateEvents (other than updating the window in question with 
calls to BeginUpdate() and EndUpdateQ, if nothing else). If a 
foreground program's window is moved about, it my reveal a 
portion of a window underneath it that wasn't revealed before. 
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That program may all of a sudden decide that, on getting it's 
updateEvent, that it wants to get some more characters from the 
modem and display them on the screen and such (like another 
program that I won’t mention who's initials [really are] UW). АП 
programs should include a Size = -1 resource, in which, if nothing 
else, they give a preferred memory partition size that they want 
to run in. If none is given, 384K is assumed (though this can be 
edited from the Get Info box in the Finder). Programs that were 
designed for the 128K Mac (in the 128K Mac days...) wind up 
taking gobs of RAM for no good reason. All programs need to 
support Desk Accessories, as it's through this mechanism that 
Major Switching takes place. Lastly, to better utilize the Multi- 
Finder environment (that allows multiple programs to be auto- 
launched on startup), programs should save their window posi- 
tions and states so that the next time that they are invoked the user 
doesn't have to fuss with moving around all of their windows to 
where he wants them. Тһе kosher way to do this is with 
GlobalToLocal() on the upper left and lower right positions of 
your window (or just the upper left if it's not resizable), and 
saving that information into the resource or data fork of another 
file (not the one that the program is in) Then call 
MoveWindow(savedPoint) to position it before making it vis- 
ible. Alternately you could save a copy of the window resource 
into a configuration file. Just keep in mind that reading and 
writing to the window record itself a no-no (says Apple), “cause 
it may change in the future. And by writing to a file other than 
the program file, you allow yourself to be shared on a network 
(such as AppleShare or TOPS). Of course, if you don't want to 
be shared, than this isn't a problem. Unless you are a commercial 
program with single-user licensing only, you may as well allow 
yourself to be shared. 


Graphic Load Average 


When I first saw MultiFinder in action, I immediately 
thought that some means of measuring the *load average' of the 
CPU was needed (after all, most all True™ multitasking systems 
havethis). Being as there was no real way to measure this in the 
traditional sense (the number of processes the CPU is actively 
switching through), I decided that instead it would measure the 
number of nullEvents it got over a period of time, and graph it's 
results (which isa more meaningful measure under MultiFinder). 

Unfortunately someone beat me to it (actually, a lot of 
people beat me to it, but one sticks out in particular). I have to 
give credit to Erik Kilk, who posted Waiting to the Usenet some 
72 hours before I had my program running. Clearly the only way 
Icould salvage my ego was to try to make my program better than 
his. 

Graphic Load Average (GLA) has four load meters, each 
of which can be set to a different sensitivity and update duration 
(and width) These settings are set via a hierarchical menu. 
Additionally it uses WNEO, and will not run if MultiFinder isn't 
present (a dialog box comes up to nicely inform you of this). Also 
there is an option to Compress Juggler RAM, which makes a call 
to the new juggler call MFMaxMem(). While I have yet to see 
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this call actually do something, certainly having it there some- 
how improves GLA (it also shows how to make the call from 
LightSpeed C v. 2.13, which doesn't yet support these new calls 
— see the modified-multifinder.h include file that I made, with 
the generous help of Ed Tecot of Apple, to use with LightSpeed 
C). [Note: The current version of LS C is 2.15. Updates are 
available from Think, or if purchased from MacTutor, from us. 
-Ed] 
Graphic Load Average Controls 


Each set of triplets controls three things: the width item, 
which is the width of the displayed graphic bar in the window, the 
ceiling, which is the number of ticks which will equal a full bar, 
and the time over which the null events will be averaged. The 
ceiling parameter is the sensitivity setting, as to how many ticks 
give a full height bar. The time parameter determines the number 
of ticks to wait before updating the display. If we set this to five, 
then we wait five ticks before updating the display with the 
average number received for that bar. We take the average, and 
divide it by the ceiling to calculate the height of the bar to be 
displayed. The ceiling is converted into pixels, divided by the 
number of ticks that equals a full ceiling to find the number of 
pixels to display. 

By using the four indicators, you can have four different 
sensitivity settings for how many ticks would result in a full bar 
display. The maximum setting is a single tick. A tick is a 60th of 
asecond. Oneachnullevent, the time is compared, so the average 
time between null events is being measured. The more bars you 
display, thé longer the time between null events, which means 
more load on the machine. 


Other points of interest and note: putting up a window in a 
saved position is all very nice, but what if the program is first run 
on a МасП, and then later is run on a MacPlus. It is important to 
check that window position is within the bounds of the window 
(better still, within the dragBounds that you use for MoveWin- 
dow(). I cheated in GLA, and took the cheap way out when it 
came to AppleShare. I wrote the configuration information into 
the same file as I execute from, which means that I cannot be 
shared under AppleShare (note: even if I was good, and wrote to 
a separate configuration file, I'd still not automatically be shar- 
able. There’s a bit [there's always a bit] that I need to set that says 
"I'm sharable, and won't do anything bad"). [As we have re- 
ported in the past, forcing developers to create hundreds of little 
configuration files is a poor excuse for Apple' s failure to build a 
resource manager that is sharable. We don' t think this is the way 
to go and don't particulary want our system file filled up with 
these things. Configuration information should be stored in a 
document instead. Documents are normally not expected to be 
sharable at the same time. In this program, Peter does another 
thing we don't recommend: he opens a specific resource file by 
file name, a definite no-no. You should obtain the application file 
name from the finder info and open the file using that name 
instead of hard-coding a file name into the source. -Ed] 
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Dear Phil and Erich 
(MultiFinder wish list) 


While I'm very happy with all that I can now do with my 
Macintosh and MultiFinder, there are still things I'd like to see 
(especially as a programmer). 


° Iwantsome way of getting mouse clicks into a window 
when that mouse click caused a Major Switch (try clicking on 
GLA’s content region in a switch, dragging, and releasing the 
mouse—GLA’s window won't drag) 


e Td like Alert and Dialog boxes that I can bring up via 
some sort of sublaunch mechanism that puts the dialog/alert 
‘program’ into the foreground and my program in the back- 
ground so that it can do work while the user takes his/her time 
responding to the dialog (I'd like a clean mechanism, not have to 
write my own 'dialog/alert displaying task' especially to do this). 


° I want to see more backgroundware from Apple. А 
MacTerminal that downloads in the background would be very 
nice. Initializing a floppy diskette in the background would be 
great (though that requires multi-threaded i/o, another nice 
feature for a future MultiFinder) 


e  [l'dlikesome kosher way of notifying a user that I need 
attention when I'm in the background. What does PrintMonitor 
know that we lowly developers don't? 


° Iwantto see documentation on this mysterious Layer 
Manager that's managing all the app layers for me behind my 
back (and not sending me mouseDowns on Major Switches). In 
return, I promise to restrain myself from playing with undocu- 
mented traps in search of it. 


e Га like language developers to be seeded as early as 
possible with things like MultiFinder so that I’m not forced to use 
MPW to program on the cutting edge (try running MPW and 
MultiFinder and the app your writing on a 2 Meg machine 
sometime, not to mention the 80% of us who have 1 Meg 
machines!) Please don't make me write glue for this—that's 
what the language developers are for. [A swift kick in the rear to 
third party develoepers to update their products when they get 
the new interfaces is also in order. -Ed] 


° I want MultiFinder to somehow guarantee my back- 
ground task a nullEvent at least every so often, so that my 
communications software doesn't time out due to it not getting 
any time. Just a little pre-emption so that connections don't die 
just because MicroSomeone's software decides to keep the CPU 
longer than it should have. 


° Iwanttheplayingofsoundsto notkill all user i/o. I want 
to be able to type characters and switch between programs while 
sound is playing. How about some more background tasks guys? 
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/* Graphic Load Average 
€ 1987 Peter Korn 


This is a little program designed 

to run in the backround under MultiFinder. 
1475 purpose: to graphically indicate 
the ‘load’ by creating а column chart of 
the load. 


х/ 

/* Defines */ 

"def ine NIL Ü 
"define nul 1StopMask 0 
def ine MYALERT 128 
ttdef ine MYDIALOG 150 
"def ine MYWINDOW 128 
"def ine DESK. 10 128 
"def ine FILE_ID 129 
"def ine Е0ІТ. 10 130 
"def ine CONF IGURE 10 131 
def ine BASE. ID 200 /* heirarchical menus */ 
'tdef ine WINDOW. POSh 150 
"gef ine WINDOW. POSv 151 
def ine BAROFFSET 10 
#def ine WNETrepNum 0x60 
def ine UnImplTrepNum | £x9F 
"def ine SUSPEND_RESUME_EVT 15 
"def ine SUSPEND.RESUME.BIT 0 
"def ine CLIPBOARD.BIT 0 
def ine MessageDialog 258 


/* Includes */ 


"include <Quickdraw.h? 
*include «MacTypes .? 
"include «FontMgr .h» 
8Sinclude <WindowMgr .h> 
8include «MenuMgr .h> 
8include «TextEdit.h» 
8include <DialogMgr .h> 
®include <EventMgr .h? 
"include «DeskMgr .h? 
include «FileMgr.h» 
"include «ToolboxUtil.h» 
*include «ControlMgr.h? 
®include ‹050+11.№ 
include «ResourceMgr .h? 
* include «modif ied MultiFinder.h» 


/* Globals */ 


typedef struct ConfigurationItem ( 
int value; 
Handle valueHandle; 
MenuHandlemenuHandle; 

) ConfigurationItem; 


typedef struct Conf iguretionTriplet ( 
ConfigurationItem ceiling; 
Configurationitem ^ interval; 
ConfiguretionItem width; 


2 


struct Conf igurationTriplet theConf iguretion[4]; 


long ticksGoneBy, tickSum[4], tickSumDivider [41; 
int **windowPoshHaendle, **windowPosvHandle; 
GrafPtr theCurrentPort; 
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MenuHandle ` deskMenu, fileMenu, editMenu, conf igureMenu; 


WindowPtr loadWindow; 
$tr255 daName; 
Rect dragBoundsRect; 


/* restartProc */ 
restartProc() 


quitTimeC2; 


/* the Switches */ 


long  CeilingSwitch CitemNumber) 
int | itemNumber; 


long returnVal; 


SwitchCi temNumber ) ( 

case 1: 
returnVal 
break; 

case 2: 
returnVal = 
break; 

case 3: 
returnVal = 3; 
break; 

case 4: 
returnVal = 4; 
break; 

case 5: 
returnVal = 5; 
break; 

case 6: 
returnVal = 6; 
break; 

cese T: 
returnVal = 7; 
break; 

case 8: 
returnVal = 8; 
break; 

case 9: 
returnVal = 9; 
break; 

сазе 10: 
returnVal = 10; 
break; 

case 11: 
returnVal = !5; 
break; 

case 12: 
returnVal = 20; 
break; 

case 13: 
returnVal = 30; 
break; 

case 14: 
returnVal = 60; 
break; 


1; 


' 
м 
me 


) 


return(returnVal); 

long IntervalSwitchC i temNumber 2 
int itemNumber ; 
long returnVal; 


switch( i temNumber ) ( 
case 1: 


© The Definitive MacTutor, Vol. 4 


returnVal = 1; DielogPtr dialogP; 


break; int item; 
case 2: 
returnVal = 2; ParamText(message®, messagel, message2, message3); 
break; dialogP = GetNewDialog(MessageDialog, (Ptr NIL, (Ptr)-1); 
case 3: if CdialogP == NIL) ( 
returnVal = 5; SusBeep(5); 
break; ExitToShel1(); 
case 4: 
returnVal = 10; else ( 
break; InitCursor(); 
case 5: ModalDialog(C(Ptr NIL, item); 
returnVal = 20; DisposDialog(dialogP); 
break; ) 
case 6: ) 
returnVal = 60; 
break; /* setUpWor]d */ 
case T: 
returnVal = 120; setUpWor]d() 
break; ( 
case 8: int 15 
returnVal = 180: SysEnvRec theWorld; 
break; 05Егг егг; 
case 9: 
returnVal = 600; InitGref C&thePort); 
break; InitFonts(); 
case 10: FlushEventsCeveryEvent, nul 1StopMask ); 
returnVal = 1200; Ini tWindowsC); 
break; InitMenus(); 
TEInit(); 


InitDialogs(restartProc); 
return(returnVal); 


InitCursor(); 
long  WidthSwitchCitemNumber 2 /* check if WNE is implemented, and exit if not 
int itemNumber ; ...Stolen from Tech Note #158 x/ 
err = SysEnvironsC1, &theWorld); 
long returnVal; if CCtheWorld.machineType < 0) || 
(NGetTrapAddressCWNETrepNum, ToolTrap) == 
SwitchCitemNumber)( NGetTrapAddressCUnImplTrepNum, Тоо1Тгар))) ( 
cese 1: doMessage("\pMultifinder not active", ^^, "^, 97); 
returnVal = 1; ExitToShe11C); 
break ; 
case 2: SetRect(&dragBoundsRect, screenBits.bounds.left +4, 
returnVal = 2; screenBits.bounds.top + MBarHeight, 
Pia ScreenBits.bounds.right -4, screenBits.bounds.bottom -4); 
case 3: 
returnVal - 3; /* get saved resources & don't let “еп get purged */ 
break; 
case 4: OpenResF ileC“\pGLA appl”); 
returnVal = 4; /* note: this is not nice. Never hard code а file name. */ 
break; 
case 5: for (i20; і<4 itt) ( 
returnVal = 5; theConf iguration[i].ceiling.valueHandle = 
break ; GetResource((ResType) ‘INFO’, CBASE_ID + i*3)); 
HNoPurge( theConf igurat ion[i].ceiling.menuHandle); 
returnCreturnVal); theConf igurationli].ceiling.value = 
CeilingSwitchC**theConf igurationli].ceiling.valueHandle); 
/* doMessage */ theConf iguration[i].interval.valueHandle = 
GetResource((ResType) ‘INFO’, (BASE_ID + 1 + 1%3)); 
/* Politely inform user of messages like no HNoPurge( theConf iguret ion[ i]. interval .menuHandle); 
multifinder running. Note- this is not theConf iguration[i].interval.value = 
the kosher way to do things since it doesn’t IntervalSwi tch(** theConf iguration[i]. interval.valueHandle); 
involve string resources, which can be edited 
or translated. But it is much faster to develop. */ theConf iguration[il] .width.valueHandle = 
GetResource((ResType) ‘INFO’, (ВАЗЕ_ТО + 2 + 1*3)); 
doMessage (message® , message 1, message2, message3) HNoPurge( theConf iguration[i].width.menuHandle); 
Str255 message; theConf iguration[i].width.value = 
Str255 message 1; WidthSwi tch(** theConf igurationL i J.width.valueHandle); 
Str255 message? ; ) 


Str255 message3; 
( /* call ResError(), and set them menually if get error */ 
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windowPoshHandle = Cint **) GetResource( (ResTupe) ‘INFO’, 
WINDOW. POSh); 
HNoPurgeCw indowPoshHandle); 


windowPosvHandle = Cint **) GetResourceC (КезТуре) ‘INFO’, 
WINDOW. POSv); 
HNoPurge(CwindowPosvHandle?); 


/* if point not inside dragBoundsRect, set default*/ 

if (C**windowPoshHandle < dragBoundsRect. left) || 
(*%windowPoshHandle > dragBoundsRect.right) || 
(**yindowPosvHendle > dragBoundsRect.bottom) || 
(*%windowPosvHandle < dragBoundsRect.top)) ( 


**windowPoshHandle = Cint) CCdragBoundsRect.right - 
dragBoundsRect . lef t 2/2); 

**windowPosvHandle = (int) CCdregBoundsRect .bottom - 
dragBoundsRect . top 2/22; 


loadWindow = GetNewWindowCMYWINDOW, (Ptr) NIL, (Ptr) -1); 

MoveWindowCloadWindow, **windowPoshHandle, **window- 
PosvHandle, FALSE); 

ShowWindowCloadWindow); 


SetPor t( loadW indow); 
PenNormal(); 


) 
/* setUpMenus */ 


setUpMenusC ) 
( 
int i; 


deskMenu = GetMenuCDESK 10); 
AddResMenu(deskMenu, 'DRVR'); 
InsertMenuCdeskMenu, 2); 


f ileMenu = GetMenuCFILE_ID); 
InsertMenuCf i leMenu, 0); 


editMenu = GetMenuCEDIT. 102; 
InsertMenuCeditMenu, 0); 


conf igureMenu = GetMenuCCONF IGURE 10); 
Inser tMenuCconf igureMenu, 0); 


for Ci = 0; i< 4; 1++) ( 


theConf iguration[i].ceiling.menuHandle = бе Мепу(ВАЗЕ 10 
+ 1*3); 

" Inser tMenuC theConf igurationLi].ceiling.menuHendle, -1); 

CheckItemCtheConf iguration[il.ceiling.menuHandle, Cint) 
*X*theConf igurationlil].ceiling.valueHandle, TRUE); 


theConf iguration[i]. interval .menuHandle = 
GetMenu(BASE_ID + i*3 + 1); 

Inser tMenuC theConf iguration[ il. interval.menuHandle, -1); 

CheckItemCtheConf iguration[i]. interval .menuHandle, Cint) 
**theConf igurationli]. interval .valueHandle, TRUE); 


theConf igurationli].width.menuHandle = GetMenuCBASE_ID + 
i*3 + 2); 

Inser tMenu( theConf iguration[i].width.menuHandle, -1); 

CheckI tem( theConf iguration(i].width.menuHandle, Cint) 
шаа ыы ыы ТЕШЕ); 


DrawMenuBar(); 
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/* doMenu */ 


doMenu(menuResult) 
long  menuResult; 
int menuID, itemNumber, newHPos; 
int newVPos, itemHit, i, configSetting; 
long longPointer ; 
ProcPtr myFilterProc; 


/* if (menuResult == (long) NIL) 
menuResult = MenuChoice(); */ 


nenuID = HiWord(menuResult); 
itemNumber= LoWord(menuResult); 


switchCInenuID) 


case DESK ID: /* Apple Menu */ 
if CitemNumber == 1)( 
AlertCMYALERT, NIL2; 
break; 


else if CitemNumber == 0) /* b/c of nested menus */ 
break; 
else 


GetItemCdeskMenu, itemNumber, &daName); 
GetPortC&theCurrentPor t); 
OpenDeskAcc(&daName 2; 

SetPor tC theCurrentPort); 


break; 
) 
break; 
case FILE_ID: /* the File Menu */ 
swi ~ itemNumber 2 
case 1: /* the print command — */ 
break ; 
case 2: /* the quit command */ 
quitTimeC); 
break; 
break; 
сазе EDIT. 10: /* the Edit Menu */ 
SwitchCitemNumber)( 
case 1: /* the undo command */ 
break; 
case 2: /* just dashed lines  */ 
break; 
case 3: /* the cut command */ 
break; 
case 4: /* the copy command */ 
break; 
case 5: /* the paste command — */ 
break; 
case 6: /* the clear command %/ 
break; 
break; 
case CONF IGURE 10: /* the Configure Menu */ 
switchCitemNumber)( 
case 1: /* Set Time: Heirarchical */ 
case 2:  /* Average Over: Heirarchical */ 
case 3: /* Set Width:Heirarchical */ 
break; 
case 4: /* spacer */ 
break; 
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case 5: /* Set Time: Heirarchical */ 
case 6: /% Average Over: Heirarchical */ 
case T: /% Set Width: Heirarchical */ 


break; 
case 8: /* spacer */ 
break; 
case 9:  /* Set Time: Heirarchical */ 


case 10: /* Average Over: Heirarchical */ 
case 11: /* Set Width: | Heirerchical */ 
break; 
case 12: /* spacer */ 
break; 
case 13: /* Set Time: Heirarchical */ 
case 14: /* Average Over: Heirarchical */ 
case 15: /% Set Width: | Heirarchical */ 
break; 
case 16: /% spacer */ 
break; 
case 17: /% compress juggler RAM... */ 
MFMaxMem(& longPo inter ); 
break; 
} /* end switch */ 
break; 


case BASE_ID: 

case (BASE_ID + 3): 
case (BASE_ID + 6): 
case (BASE_ID + 9): 


configSetting = ((menuID - BASE_ID)/3); 

Check Цет( theConf igurat ion [conf igSetting).ceiling.menuHandle, 
Cint) **theConf iguration[conf igSetting] .ceiling.valueHandle, 
FALSE); 

**theConf iguration[conf igSett ing] .ceil ing. valueHandle 
= (SignedByte) itemNumber ; | 

CheckItemCtheConf igurat ion [conf igSetting].ceiling.meruHandle, 
(int) **theConf iguration[conf igSetting].ceiling.valueHandle, 
TRUE); 

theConf iguration[conf igSetting].ceiling.value = 
CeilingSwitchCitemNumber ); 

break; 


case (BASE_ID + 1): 
case (BASE_ID + 4): 
case (BASE_ID + 7): 
case (BASE_ID + 10): 
configSetting = (menuID - BASE_ID - 12/3; 
Check I teml theConf iguration{conf igSet ting]. interval .menuHendle, 
Cint) **theConf iguration[conf igSetting]. interval .valueHandie, 
FALSE); 
**theConf igurat ion[conf igSetting]. interval .valueHandle 
= (SignedByte) Ci temNumber ); 
Check I teml theConf igurat ion[conf igSet ting]. interval .menuHandle, 
(int) **theConf iguration(conf igSetting]. interval .valueHandle, 
TRUE); 
theConf iguration[conf igSetting]. interval.value = 
IntervalSwitchCitemNumber ); 
break; 


case (BASE_ID + 2): 
case (BASE_ID + 5): 
case (BASE_ID + 8): 
case (BASE_ID + 11): 
configSetting = (menuID - BASE_ID - 22/3; 
Check I tem theConf igurat ion[conf igSett ing] .width.menuHandle, 
Cint) **theConf iguration[conf igSetting] .width.valueHandle, 
FALSE); 
| жж theConf igurat ion[conf igSett ing) .width.valueHandle 
= (SignedByte) itemNumber; 
CheckItemCtheConf igurat ion [conf igSett ing] .width .menuHendle, 
(int) **theConf iguration[conf igSett ing) .width.valueHandle, 
TRUE); 
theConf iguration[conf igSetting].width.value = 
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WidthSwitchCitemNumber 2; 
break; 


) 
HiliteMenu(0); 


/* doLoad */ 


= 
long currentTicks, deltaTicks, barHeight, barWidth; 
long leftEdge, rightEdge, topEdge, bottomEdge; 
Rect loadBar, eraseBer; 
int di 


/* semple the load */ 

currentTicks = TickCount(); 

deltaTicks = currentTicks - ticksGoneBy; 
ticksGoneBy = currentTicks; 


/* increment accumulators and draw load */ 
for (i58; ií «4; i++) ( 
tickSum[i] += deltaTicks; 
tickSumDivider[i1**; 
if CtickSunLi) > theConf igurationL[il. interval.value) ( 


leftEdge = 5 + Ci * BAROFFSET); 
bottomEdge = 35; /* will become resizable %/ 
topEdge = 0; 


barWidth = theConfiguration[i].width. value; 


barHeight = (40 - CCtickSumli] * 35)/ 

(tickSumDivider[i] * theConfiguration[i).ceiling.value))); 
/* eliminate decimals */ 

SetRect (&loadBer, leftEdge, barHeight, leftEdge + 
barWidth, bottomEdge); 

SetRect (&eraseBar, leftEdge, topEdge, leftEdge + 
barWidth, barHeight); 

EraseRect(&eraseBar ); 

PaintRect(&loadBar ); 


tickSun[i] = 0; 
tickSumDividerli] = 0; 
} /* endif */ 
} /* endfor */ 


/* quitTime */ 
ы 
/% time to write resources, etc. */ 
int i; 
Point p; 
for (i20; í < 4; i++) ( 
ChangedResource( theConf igurationli] .ceiling.valueHandle); 


ChangedResource( theConf iguration[i]. interval .valueHandle); 
ChangedResource( theConf iguration[i].width.valueHandle); 


SetPortCloadWindow); 


LocalToGlobal(&p); 


**windowPoshHendle = p.h; 
**windowPosvHandle = p.v; 


ChengedResourceCCHendle) windowPosvHandle?); 
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ChangedResource( (Handle) windowPoshHandle); 
ExitToShe11O; 


/* main */ 


nainC) 


/* variables */ 


EventRecord theEvent; 

Point eventPt; 

char eventChar ; 

WindowP tr whichWindow, eventWindow; 

short windowCode, stillInGoAway, controlCode, whichItem, 
screpIndex; 


setUpWor1ldC); 
se tUpMenus(); 


while (ТЕШЕ) ( 
WeitNextEventCeveryEvent, &theEvent, (long) NIL, 
(RgnHandle) NIL); 
Switch (theEvent.what)( 
case SUSPEND. RESUME EVT : 
if € ! BitTstC (Ptr) theEvent . message, 
SUSPEND. RESUME. ВІТ22 /* suspend event */ 


else (BitTst( (Ptr) theEvent.message, 
SUSPEND.RESUME.BIT2) /% resume event */ 


if C ! BitTstC (Ptr) theEvent.message, 
CLIPBOARD_BIT)) /* don’t convert clipboard */ 


else (BitTst( (Ptr) theEvent.message, 
CLIPBOARD.BIT)) — /* convert clipboard */ 


7 
break; 
case mouseDown: 
eventPt = theEvent.where; 
windowCode = FindWindowCeventPt, &eventWindow); 
switch (windowCode) ( 
cese inSysWindow: 
SystemClick(&theEvent, eventWindow); 
break; 
case inContent: 
/* won't work on minor switch 
b/c of compatibility issues w/Excel */ 
case inGrow: 
case inGoAway: 
if CeventWindow == loadWindow) 
DragWindowCeventWindow, eventPt, 
&dragBoundsRect ); 
break; 
case inDrag: 
DragWindowCeventWindow, eventPt, 
&dragBoundsRect ); 
break; 
case inDesk: 
break; 
case inMenuBer: 
doMenuCMenuSe lect (theEvent .where)); 
break; 
| default: 
break ; 
} /* end switch(windowCode) */ 
break; 


case keuDown: 
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case autoKey: 
eventChar = theEvent.message; 
if (theEvent.modifiers & cmdKeu) ( 
doMenu(MenuKeu(eventChar')); 
HiliteMenu(0); 


break; 

case activateEvt: 
break; 

case updateEvt: /* absolutely necessery*/ 
BeginUpdateCtheEvent . message); 
EndUpdate( theEvent . message); 
break; 

case nullEvent: 
doLoad( ); 
break; 

defeult: ; 

) /* end of case theEvent.what */ 
) /* while */ 


/* 
MultiFinder.h - MultiFinder Interfaces 


C Interface to the Macintosh Libraries 
Copyright Apple Computer,Inc. 1987 
All rights reserved. 

*/ 


"ifndef . MULTIFIN. 
"def ine —MULTIFIN__ 
8ifndef . EVENTS... 
Вега 

8ifndef . QUICKDRAW. - 
tendif 


/* MultiFinder dispatch trap */ 


"def ine -05015РАТСН ØxA88F 
define .МАІТМЕХТЕУЕМТ 0xA860 
/* Routine selector values */ 

define mfMaxMemSel 21 

"def ine mfFreeMemSel 24 

"def ine mf TenpNewHandleSel 29 
"def ine mfTempHLockSel 30 
дег ine mf TempHUnLockSe] 31 


"def ine mf TenpDisposHandleSel 32 
дег ine MFMaxMemCgrow) V 
CMF MaxMem(grow, мГМахМет$е] ) 


define MFFreeMem() V 
cMFFreeMemCmfFreeMemSel ) 


"def ine MF TempNewHandleClogicalSize,resultCode) V 
CMF TempNewHand 1e( logicalSize, resu] tCode, mf TempNewHand1eSe 1 ) 


def ine MFTempHLock(h,resultCode) \ 
CMF TempHLock Ch, resul tCode, mf TempHLockSe 1 ) 


"def ine MFTempHUnLock(h,resultCode) V 
CMF TempHUnLock (Ch, resul tCode , mf TempHUnLockSe1) 


"def ine MFTempDisposHandleCh,resultCode) V 
CMF TempD isposHand1eCh,resu] tCode, mf TenpDisposHandleSel) 
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/* WaitNextEvent was released іп MPW 2.0 interfaces. It is 
commented out below to avoid а duplicate declaration. 
Uncomment only if working with earlier interfaces. */ 


pascal Boolean WaitNextEvent(mask,event,sleep,mouseRgn) 
unsigned short mask; 
EventRecord *event; 
unsigned long sleep; 
"dais mouseRgn; 


asm ( 

SUBQ.L #2, SP 

MOVE.W 20СА6), -CSP) /* short mask*/ 

MOVE.L 16(А6), -CSP) /* long *event  */ 

MOVE.L 12(Аб), -(SP)  /* long Sleep*/ 

MOVE.L 8CA6), -CSP) /* long handle */ 

DC.W — .WAITNEXTEVENT 

MOVE.W CSP)+, 22CA6) /* return stack pointer 
state*/ 


) 


pascal long cMFMexMemCgrow, SW) 
long *grow; 
rua Sw; 


esn( 
SUBQ.L 84, SP 
MOVE.L 19(A60, -CSP) /% long *grow*/ 
MOVE.W 8(Аб), -(SP) /* short SW */ 
ОС. _OSDISPATCH 
MOVE.L CSP)+, 14CA6) /* return stack pointer 
state 4 


) 


pescal Size cMFFreeMemCSW) 
"in SW; 
esn( 
DC.W _OSDISPATCH 


) 


pascal Handle cMFTempNewHandle(ClogicalSize, resultCode, SW) 
unsigned long logicalSize; 


short *resultCode; 
short SW; 
( 
asm ( 
DC.W .05015РАТСН 
) 
pascal void cMFTempHLock(h, resultCode, SW) 
Handle h; 
short *resultCode; 
"um SW; 
asm ( 
DC.W  _OSDISPATCH 
) 


pascal void cMFTempHUnLockCh, resultCode, SW) 
Handle h; 


short *resul tCode; 
ub SW; 
esn( 


DC.W .05015РАТСН 
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) 


pascal void cMFTempDisposHendleCh, resultCode, SW) 
Hendle h; 


short *resultCode; 
short SW; 
( 
asm ( 
) DC.W _OSDISPATCH 
) 
#endif 


*Graphic Load Appl.R 
x 


GLA.rsrc 
RSRCWAKA 


Type WAKA = STR 
0 


Graphic Load Average 1006 by Peter Korn \@Dver 28 JAN 1988 
Type FREF 
8 


М 


АРР. 0 


Туре BNDL 
, 128 

WAKA 0 
ICN® 

0 128 
FREF 

0 128 


TYPE WIND 
BarWindow, 128 

load 

40 350 80 400 
Invisible МобоАнау 
3 


TYPE SIZE = GNRL 

JugglerSize, -1 

5800 0000 8000 0000 8000 ;; gotten by looking at Size = -1 
resource aS general 


TYPE MENU 
AppleMenu, 128 

\14 

About Load Average 
(- 


FileMenu, 129 
File 

(Print/P 
Quit/Q 


EditMenu, 138 
Edit 


(Clear /B 
Conf igureMenu, 131 


Conf igure 
Tick ceiling/MB! \С8 
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Interval time/\1B!\C9 
Measurement width/\1B!\CA 
(- 

Tick сеі1іпо/\ 18! \СВ 
Interval time/N1B! CC 
Measurement width/\1B!\CD 
(- 

Tick ceiling/\1B!\CE 
Interval time/\1B!\CF 
Measurement width/\1B!\DØ 
(- 

Tick ceiling/\1B!\D1 
Interval time/\1B!\D2 
Measurement width/\1B!\D3 
(- 

Compress juggler RAM 


CeilingiMenu, 200 
Ceilingl 


O Со Ш O, Q! > WN — 


IntervaliMenu, 201 
Intervall 


600 
1200 


WidthiMenu, 202 
Width! 

1 

2 

3 

4 

5 


Ceiling2Menu, 203 
Се111пд2 
1 


Interval2Menu, 204 
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Interva12 


Width2Menu, 205 
Width2 


сл > GW м — 


Ceiling3Menu, 206 
Ceilings 


[d 


Interval3Menu, 207 


Interval3 


Width3Menu, 208 
Widths 


Ceiling4Menu, 209 
Ceiling4 


O со -ч С Q) & CO PO — 


60 


Interval4Menu, 210 
Interval4 


Width4Menu, 211 
Width4 

1 

2 

3 

4 

5 


ж Progrem Messages 018109 box... 


type DLOG 
,258 


Progrem Messages 
100 100 200 400 
Visible МобоАнау 
1 


0 
258 


type DITL 

3 

BtnItem Enabled 
65 230 95 285 
OK 


StatText Disabled 
15 68 85 222 
“@ OD 11007210073 


IconItem Disabled 
10 10 42 42 
1 


TYPE INFO = GNRL 
Window Pos h, 150 


0060 ;; initial hor window position 


Window Pos v, 151 


0060 ;; initial ver window position 


Ceilingl1, 200 
01 


;; initial Ceiling! value 


Intervali, 201 


01 ;; initial Intervall value 


Width1, 202 
05 


Ceiling2, 203 


;; initial Width! value 


02 ;; initial Ceiling2 value 


Interval2, 204 


02 ;; initial Interval2 value 


Width2, 205 
05 


2; initial Width2 value 


© The Definitive MacTutor, Vol. 4 


Ceiling3, 206 
03 


Interval3, 207 
03 


Width3, 208 
05 


Ceiling4, 209 
04 


Interval4, 210 
05 

Width4, 211 

05 


ТҮРЕ МЕТ 


MyAlert, 128 (2) 
79 139 192 450 


128 
4444 


TYPE DITL 


ee 
24 


44 


.. 
44 


44 


; initial Ceiling3 value 


initial Interval3 value 


initial Width3 value 


initial Ceiling4 value 


initial Interval4 value 


; initial Width4 value 


MyDialogList, 128 (2) 
4 


ButtonItem Enabled 
81 127 101 177 


OK 


StetText Enabled 
8 78 28 228 
Graphic Load Average 


StatText Enabled 
28 78 48 228 
written by Peter Korn 


StatText Enabled 
93 9 72 294 


Portions of this code ® Think Technologies 


Туре ICN! = GNRL 
,128 (0) 
H 


0000 0000 0000 0000 GOFF FF80 0300 0060 
0400 0010 0800 0008 1000 0004 1000 0004 
2000 0002 2000 0002 2000 0002 2000 Ғ002 
2000 Ғ002 2000 Ғ002 2000 Ғ002 2000 Ғ002 
21Е0 Ғ002 21Е0 Ғ002 21Е0 Ғ002 21-0 Ғ0Е2 
21Е0 FOE2 21Е0 FOE2 21Е0 FOE2 21Е0 Ғ0Е2 
11Е0 FOE4 11Е0 FOE4 Ø9EØ FOES 05Ей FOFO 
ОЗЕВ РЕФ OFF ҒҒ80 0000 0000 0000 0000 
x 

FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
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C Workshop 


Don Melton and Mike Ritter 
Impulse Technologies, Inc. 
Santa Clara, California 


Tear-off Menus & Floating Palettes TearOffPalette MacTutor Vol. 4 No. 4 


Don Melton is the Computer Graphics Specialist for the San 
Jose Mercury News and does technical support for the Knight- 
_ Ridder Graphics Network. His partner, Mike Ritter, is a Ке- 

search Scientist at Lockheed’ s Palo Alto Research Laboratories 
in the Electro-optics Department. In their spare time they do 
MacHacking for their own company, Impulse Technologies, Inc. 


Introduction 

Why TearOffPalette? Well, ever since we saw HyperCard 
we've been wondering, just like everyone else, how Bill Atkin- 
son did that impressive tear-off menu effect. Of course, the 
wizardry Andy Hertzfield performed with Radius's new moni- 
tors caught our eye, too. If you haven't seen Andy's ROM- 
defying performance, take a look — he makes any menu tear off! 

And now everyone wants to get into the act. 

Daryl Lovato gave many of us our first clues toward making 
menus leave their home in his article titled “Tear-Off Menus 
Explained" in December's MacTutor. But he still left many 
questions unanswered, like how do you get the darn palettes to 
‘float’ above other application windows (which we call docu- 
ments to differentiate them from the floating palettes). And he 
didn'tuse those stylish HyperCard title bars in his palettes either. 

We also noticed that all of the applications we saw which 
used tear-off menus had some rather strange ‘features’ in them. 
Our first attempt to do the tear-off trick simply mimicked 
HyperCard. The constant flashing of menu items soon drove us 
batty. Then there's Bill's highlighting (or lack thereof) of his 
main window when a menu is torn off. 

Then we saw the new MacPaint. Sure, the highlighting is 
better but the palettes are in a fixed order! Even HyperCard 
doesn't do that. Two steps forward and one step back. That's 
progress. 

If only Apple would just torture Andy Hertzfield until he lets 
them release his code as system software. Alas, Radius has to 
maintain its market advantage. Maybe if everybody buys enough 
Radius monitors Burrell Smith may let the cat out of the bag. 

Until then ... we decided to show you how it can be done. 
And how to make it nice and modular too — with one application, 
an MDEF and a WDEF. Using our code any developer can 
implement tear-off menus and floating palettes in their applica- 
tion. Really. As a bonus, our source code will also demonstrate 
how to: 

° Work with MultiFinder using WaitNextEvent() 

• Use Color QuickDraw to implement a full-color palette 

* Respond to suspend/resume events 

• Write a fully-working, albeit simple, grow zone function 

And it has extensive error checking built right in. Enough to 
function correctly with strict trap discipline and heap check, 
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Edit 


File Edit Tool Pattern Color 


€ File Edit Tool Pattern Color 


Fig. 1 Tear off palette menus that float on top! 


scramble and purge, all set in TMON, while it runs concurrently 
under MultiFinder with ResEdit and any Microsoft application. 
Just about the nastiest environment a Mac developer could 
imagine. 

Italso (ta da/) works with any Macintosh. That's right, even 
those lonely ones in the corner with 64K ROMS. 
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Before we get to the code though, we'd like to cover some 
user interface considerations, the proper use of menu and win- 
dow definitions, some guidelines for using our special MDEF, 
and a general explanation of how the whole thing works. 


User-Interface Thought Police on Patrol 

We're going to pretend we're Apple Computer and tell you 
how tear-off menus and floating palettes should behave. After all, 
we are writing this with plural pronouns. 

Before a menu is torn off it must act like a normal menu. The 
currently selected item must be highlighted when the menu is 
drawn. The current item must be unhighlighted and another item 
must be highlighted as the mouse is tracked through the menu. 
When the mouse button is released within the menu, the high- 
lighted item must flash and become the currently selected item. 

When the mouse is more than 15 pixels outside the menu, a 
gray outline of the palette must track the mouse until the button 
is released or the mouse moves back within the menu or menu 
bar. The mouse must be 'stuck' to the top center of the gray 
outline, just as if it were dragging a window by its title bar. If the 
mouse button is released outside the 15 pixel boundary, a floating 
palette must appear within the gray outline. See Figure 1. 

If a non-application window is the front window when the 
menu is torn off, the top-most document and any other floating 
palettes must be brought in front of that non-application window. 
The torn-off menu must then become the top-most palette. The 
top-most document or other floating palettes must never be 
unhighlighted when a menu is torn off. See Figure 2. 

Floating palettes must always remain above documents in 
their own layer and they must have a user-selectable order in that 
layer. If the only visible document is closed, all of the palettes 
must remain visible. 

In a non-multitasking environment, whenever a non-appli- 
cation window is brought to the front, the top-most document and 
all floating palettes must be unhighlighted. See Figure 3. Under 
MultiFinder, whenever another application is brought to the 
front, the top-most document must be unhighlighted and all of the 
visible palettes must be hidden. When the application is brought 
back to the front, all hidden palettes must be made visible and the 
top-most document must be highlighted. 

Whew! And you thought Apple was stuffy in their “Human 
Interface Guidelines: The Apple Desktop Interface," a recent 
must-read publication from Addison-Wesley. If you've got a 
copy handy, turn to pages 90 through 92 and see how close our 
definitions match. 

Hmmm. We seem to be much more specific about certain 
details. Why? Well, after using HyperCard and the new 
MacPaint we began to notice some of the quirks we mentioned 
earlier. Some behavior just didn't seem to conform to the stan- 
dard Macintosh user interface. Like not unhighlighting floating 

palettes when a desk accessory is broughtto the front. Which then 
_ 1$ active, the desk accessory or the application? If the windows 
don't overlap, the user can easily become confused. 

Tear-off menus and floating palettes shouldn't break any of 
the other normal interface guidelines. Think of them as an 
extension or super-set of the regular Mac interface. Also, always 
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remember Scott Knaster's rule, “Apple is not God." That's why 
we don't require the user to hold down the infamous command 
key to tear off a menu. That rule reeks of modality. Why make the 
convenience of tearing off a menu with the mouse more incon- 
venient by having to use the keyboard? Obviously Bill Atkinson 
feels the same way. And remember, HyperCard is system soft- 
ware. 

Of course, if you hold down the command key, our menus 
will still tear off. 

And don’t beconfused by Apple’s insistence that “if a single 
application can have more than one menu torn off at a time, the 


Untitled === 


Fig. 3 But it correctly allows DA windows on top! 


application must determine their order of precedence." Of 
course, floating palettes must always be in some order. But the 
application should let the user determine that order by clicking 
the mouse in the title bars of the palettes. It's still a determined 
order of precedence, just not fixed. 
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We did add one extension to our application's user interface 
and it has nothing to do with tear-off menus or floating palettes. 
It's something that we think the Mac has needed for quite awhile. 
In fact, Mike Schuster performed a similar extension with Adobe 
Illustrator. This is simply to allow the user to send a window to 
the back by holding down the option key and clicking on the 
window’ s title bar. And we extended this extension to include the 
palettes. A floating palette can be sent underneath all of the other 
visible palettes in the same manner. 

Also, just like the Finder, if the option key is held down while 
closing one of our application windows, all open windows are 
closed. 


Writing the Darn Thing 

So now that we've decided what we want to do, how do we 
go about doing it? 

Well, we could use Andy Hertzfield's method but it's very 
complex. Of course, since Andy's a genius you'd expect that. 
Andy decided to patch several Window Manager traps and lie to 
the ROM about what's actually going on in the Window Manager 
port. He also plays hide-and-go-seek with the Menu Manager and 
a lot of other system software. We decided not to get that low- 
level with our code since we're only planning to tear off a few of 
our application's menus. 

First, to create a menu that will tear off, a menu definition 
must be written. If that torn-off menu will display a palette that 
looks different from a standard window, then a window defini- 
tion must be written. Daryl Lovato showed us this much. But to 
make those palettes float above application documents, without 
patching any traps, substitutes for certain Window Manager 
routines must be implemented within the application code. 

Ofcourse, we could just rewrite the entire Window Manager 
as a library and link it with our code. Anyone have а lot of time 
on their hands? Just kidding, we'll get to this later anyway. 

Since the first job seems to be writing menu and window 
definitions (MDEFs and WDEFs), we can just jump right in. 
Right? Well ... there's a little disagreement, and even more 
confusion, about how these MDEFs and WDEFs should be put 
together. 

MDEFs and WDEFs are called by the Macintosh ROM to do 
things like draw a menu or highlight a window. The System file 
and newer versions of the ROM contain the standard definitions 
as separate resources. Apple recommends that whenever you 
have to display non-standard menus, windows, etc., you should 
write and compile these routines as separate resources and move 
them into your application. 

Іп reality almost nobody, including Apple, does it this way. 

Most folks create the definitions as a part of their normal 
application code and at runtime make the ROM call their code as 
if itexisted in a separate resource. However, there is a right way 
and a wrong way to do this. Let us explain MDEFs first. 


Using a Menu Definition 
One of the fields of a MENU resource is the procID. This is 
ashortinteger containing the resource ID of the MDEF to be used 
by the Menu Manager to draw, highlight, etc., the menu. When 
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the menu is inserted into the menu list, the Menu Manager 
replaces the procID and the following filler field, also a short 
integer, with a handle to the MDEF. Thus one long, the handle, 
replaces two shorts, the procID and filler, in the menuProc field 
of a Menulnfo record. 

Have you noticed that the resource seems to be arranged a bit 
differently than the MenuInfo record? Relax, it works fine 
because the whole thing is really the same size. 

Normally the procID contains 0 torefer to the default MDEF 
in the system. Programmers who create their own separate 
MDEF code resources place the ID of their MDEF in a MENU 
resource's procID. This is the Apple approved method. It works 
too, but it's more difficult for non-standard MDEFs to be com- 
pletely separate since they usually contain information specific 
to the application which must be drawn or highlighted. Some 
method of communicating with the application must exist. That’s 
why so many programmers leave the menu definition in their 
application code, so it can access their own global variables and 
such. 

How is that done? One method is too leave your MENU 
resource with a 0 in its procID, insert the menu into the menu list, 
and then place a handle to a routine in your application code in 
the menuProc field that will behave like a normal MDEF. The 
tricky part is creating a handle to your own code. This is where 
some programmers try to be clever and wind up doing something 
very dangerous with Macintosh memory management. Here’s 
the dangerous evil mutant method: 


DangerousMethod() { 
MenuHandle myMenuHdl; 


/* Get a handle to the menu 

and insert it into the menu list. */ 
myMenuHdl = GetMenuCMENU.ID2; 
InsertMenu(myMenuHdl, 0); 


/* Point menuProc et empty block on the heap. */ 
C*myMenuHd12-»menuProc = NewHandleC2); 
/* Arrggh! 
Aim the block’s master pointer at your code!? */ 
* (*nyMenuHdl2-? menuProc 

= (Ptr) MenuDef intionFunction; 


/* Force the menu size to be recalculated 
after it’s inserted. */ 
CalcMenuSizeCmyMenuHd] 2; 


DrewMenuBar( ); 


Never, never, never change the contents of a master pointer 
this way! As soon as you do, the block to where it formerly 
pointed no longer exists as far as the memory manager is 
concerned. And worse still, the block to where it now points is 
inside another block. Strange and evil things can begin happen- 
ing to your heap. For more information on this phenomenon, 
consult Tech Note #117, pages 17-19. Apple has some very strict 
precautions against using this technique. 

So how do you get a handle to your code? It’s so simple it’s 
scary. Puta handle to a routine that will jump to your application 
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code іп the menu's menuProc field. What? Another routine? 
Aren't we going in circles here? Nope, just create it at runtime. 
Let's define a new type of structure and a new constant: 


typedef struct JumpRecord ( 
short instruction; 
void (*function)(); 
) JumpRecord, **JumpHandle; 


8def ine JMP. INSTRUCTION 0х4еҒ9 


Figured it out? Right! АП we have to do is allocate one of 
these records as a relocatable block on the heap, put the value of 
a 68000 jump instruction in the first field and the address of the 
menu definition in the second field. Voila! When the ROM looks 
at this it will see: 


JUMP MenuDef initionFunct ion 


Sneaky? Yeah, but it's one safe and sane method that's also 
perfectly legal. Here's how you set it up: 


SafeAndSaneMethod() ( 
MenuHandle myMenuHd!; 
JumpHendle menuDef Jump; 


/* Get & handle to the menu 

and insert it into the menu list. */ 
myMenuHd] = GetMenuCMENU. 10); 

Inser tMenuCmyMenuHdl, 0); 


/* Allocate а JumpRecord on the heap. */ 
menuDef Jump 
= (JumpHandle)NewHandle(sizeof (JumpRecord)); 


/* Init JumpRecord to point to your code. */ 
C*menuDef Jump)-> instruction = JMP INSTRUCTION; 
(*menuDef Jump2-? function = MenuDef initionFunction; 


/* Point menuProc at JumpRecord on the heap. */ 
(*myMenuHdl)-?menuProc = (Handle) menuDef Jump; 


/* Force the menu size to be recalculated 
after it’s inserted. */ 
CalcMenuSizeCmygMenuHd12); 


DrawMenuBar С); 


Now some might argue that this forces the application to 
become a compiler. In a sense that's true, but the same argument 
could be made for any variable initialization done by an applica- 
tion. Hey, it works. And it works well. 

There's one important thing you need to remember when 
you're going to have the ROM call your application code. Never 
let your code move! If you give the ROM a pointer, it better point 
tothe real thing. This means that the menu definition better reside 
in a code segment that's always available and always locked. 
Place it in your main segment and you shouldn't have to worry. 

There's a variation on the safe and sane method that's 
definitely worth mentioning. You don't have to create the 
JumpRecord at runtime. Instead, you can create an MDEF 
resource that's the same size as the record, have the ROM read it 
in, and initialize it the same way. And it even saves a few lines of 
code. Other than that, there's no functional difference at all. 
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Here's an example: 


OtherMethodC) ( 


JumpHandle menuDef Jump; 
MenuHandle myMenuHd] ; 


/* Get a handle to the MDEF. */ 
nenuDef Jump 
= CJumpHandle Ge tResource(‘MDEF’, MDEF_ID); 


/* If the first word of the MDEF resource 
contains Qx4ef9 then there’s no need to 
initialize the jump instruction here. */ 


/* Initialize the MDEF to point to your code. */ 
C*menuDef Jump)-> function = MenuDef initionFunction; 


/* Get а handle to the menu 

end insert it into the menu list. */ 
myMenuHd! = GetMenuCMENU_ID); 

Inser tMenuCmyMenuHd], 0); 


/* There's no need to force the menu size 
to be recalculated. */ 


DrewMenuBar(); 


By the way, if you place a different number in the procID of 
a MENU resource, a corresponding MDEF must be available at 
runtime or the Menu Manager is particularly unforgiving; i.e., a 
system error will occur. 


Using a Window Definition 


WDEFs usually don'tneed to communicate with an applica- 
tion because they just draw the window frame. The contents of a 
window are (and should) always be handled by the application 
itself inits update function. Of course that doesn't mean youcan't 
include a window definition in your application code. It's just not 
as necessary. 

If you're going to write a separate WDEF, like we did, you 
still have one thing you must do: pass the correct procID to 
NewWindow(). “Inside Macintosh Volume I,” page 298, ex- 
plains this whole process in detail. Since the standard WDEF's 
resource ID is 0, most programmers don't know they're calculat- 
ing the procID like this when they create a window: 4 


procID - (16 * resource ID) * variation code 


Obviously (16 * 0) + noGrowDocProc would still equal 
noGrowDocProc, so most of us never notice this. Here's an 
example in context: 


UseRealWDEFC) ( 


WindowPtr myWindow; 


myWindow = NewWindow(p, bounds, title, visible, 
(16 * WOEF_ID) + noGrowDocProc, behind, 
goAwayF lag, refCon); 


However, if your window definition is going to reside in 
your application code, you'll have to do things a bit differently. 
If you use the six byte jump table WDEF in a resource (like we 
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did with the MDEF), you're going to have to initialize it first 
before you pass its ID to NewWindow(). Why? Because the 
WDEF code is executed when the window is created. If you don't 
have the address to the function stored in the jump table, the ROM 
will jump to the flaming pits of Hell. Not a nice thing to happen. 
So here's how it can be done correctly: 


UseJunpTebleWDEFC) ( 
JumpHandle windowDef Jump; 
WindowPtr myWindow; 


/* Get а handle to the WDEF. */ 
windowDef Jump 
= (JumpHandle )GetResource( ‘WDEF’, WDEF_ID); 


/* If the first word of the WDEF resource 
contains Ox4ef9 then there's no need to 
initialize the jump instruction here. */ 


/* Initialize the WDEF to point to your code. */ 


C*windowDef Jump 2-? funct ion 
= WindowDef initionFunction; 


/* Now it’s safe to create the window. */ 
nyWindow = NewWindow(p, bounds, title, visible, 


C16 * WDEF_ID) + noGrowDocProc, behind, 
goAwayF lag, refCon); 


If you’d rather create the jump table at runtime (like we also 
did with the menu), there is one limitation: your window defini- 
tion won’t be able to respond to a wNew message (See “Inside 
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Macintosh Volume 1,” pages 298-302). This is because there 
isn't any real resource to pass to NewWindow0 in the procID, 
and a wNew message is executed only when the window is 
created. A real chicken-before-the-egg problem. But, most of the 
time this is no big deal, so here's how it's done: 


UseOnlyAJumpTebleC) ( 
WindowPtr myWindow; 
JumpHandle windowDefJump; 


/* Create window, but don’t make it visible. */ 
myWindow = NewWindow(p, bounds, title, FALSE, 
noGrowDocProc, behind, goAwayFlag, refCon); 


/* Allocate а JumpRecord on the heap. */ 
windowDef Jump 
= (JunpHandle)NewHandle(sizeof CJumpRecord)); 


/* Init JumpRecord to point to your code. */ 
(*windowDef Jump2-? instruction = JMP. INSTRUCTION; 
(*windowDef Jump2-? function = WindowDef intionFunction; 
/* Point windowDefProc et JumpRecord on heap. */ 
((WindowPeek) myWindow2-?windowDefProc 

- (Handle) windowDef Jump; 
/* Now you can make the window visible. */ 


ShowW indowCnyWindow); 
) 


Whatever you do, don't try the evil mutant method again! 
Here's a real dangerous way to get your code executed: 
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Fig. 4 The right and wrong of definition routines 
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DangerousMethodForWindowsC) ( 
WindowPtr myWindow; 


/* Create window, but don’t make it visible. */ 
myWindow = NewWindow(p, bounds, title, FALSE, 
noGrowDocProc, behind, goAwayFlag, refCon); 


/* Point windowDefProc at empty block on Неар. */ 
CCWindowPeek) myWindow)->windowDefProc 
= NewHand1e(@); 


/* Arrggh! 
Aim the block’s master pointer at your code!? */ 
*(CWindowPeek) myW indow)-) windowDef Proc 

= (Ptr) WindowDef intionFunct ion; 


/* Make the window visible. */ 
neon ыы 


Never use master pointers like this! Enough said. Figure 4 
diagrams the right and wrong way to point to your code. 


Our Solution 

So, there are many methods to connect an application to a 
definition function. Certain methods to avoid entirely. But which 
is best? There is no best way; it depends entirely upon what 
you're trying to do. Still, Apple suggests applications that ship 
should contain these definitions as separate resources. The key 
word there is ship. 

Also remember that Apple doesn’t always follow their own 
advice. And it’s advice, not the law. The. menu and window 
definitions used in HyperCard and the new MacPaint (which was 
developed at Apple before Claris even existed) are not contained 
in separate MDEF and WDEF resources. However, Bill Atkin- 
son and other folks in Cupertino know better than to use the 
dangerous methods described above. 

The reality of it is that during development it's much easier 
to keep the definition in your application code, especially if you 
use LightspeedC. Moving a separately compiled project in and 
out of another resource file is a real pain. If you write the 
definitions correctly, it’s not that much trouble to move them into 
a separate code resource at the end of your development cycle, 
providing you're not doing the last compilation the day before 
you shrink wrap your product. 

When we told a few folks in Apple Tech Support that we 
were going to write this article, they encouraged us to code our 
example with a separate MDEF and WDEF. Everyone could use 
them then. Not only would our source code be handy, but folks 
could just use ош xDEFs like libraries. Universal code. What a 
great idea! 

That was easy with the WDEF, but how do you share global 
data with a separate MDEF? Well, we had to get just a little bit 
sneaky ... 


Communicating with TearOffMDEF 
So you've probably skipped ahead and looked at the code by 
now. Confused? Serves you right for skipping ahead. It’s really 
simple. All we do is provide the basic tear-off mechanism and the 
logic to highlight and unhighlight menu items. You write all the 
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hard stuff in your application. 

What? Isn’t the MDEF separate? Sure, but it’s not clairvoy- 
ant. Somebody has to draw the menu. TearOffMDEF passes 
application specific requests made by the ROM back to the 
application. The application must first create the palette window 
to be torn off, provide three functions for the MDEF to use, and 
create and initialize a structure that will be used to contain global 
information. 

Our TearOffMDEF communicates with an application viaa 
TearOffMenuGlobals structure in a TOMG resource. What's a 
TOMG resource? Well, it's a 28-byte block with nothing but 
zeroes in it. But we'll fill it up quickly. At runtime, Tea- 
rOffMDEF uses the menuID of the MenuInfo record passed to it 
by the Macintosh ROM to find a TOMG resource of the same ID. 

Okay, let's make sure we're clear on this. A MENU resource 
has an ID. One of its fields also contains an ID. They're usually 
the same, too. Obviously this sub-ID can be found with a handle 
to the menulnfo record, because the menulnfo is basically a 
duplicate of the original MENU resource. TearOffMDEF uses 
this sub-ID to find a TOMG resource. Why? This way the 
application and the MDEF can share global information without 
ever referencing a compiled offset of address register 5. They 
don't have to share any of the same source code files. They just 
need to define the structures the same way. 

Yes, we thought it was pretty clever. 

Here'sthe way the global structure should be declared by the 
application: 


typedef struct TearOffMenuGlobals ( 

void (*drawMenuProc)(); 

short (*findItemProc)O; 

void (*hiliteltemProc)(); 

SysEnvRec *environment; 

WindowPtr paletteWindow; 

Point position; 

short currentItem; 

Boolean itemHilited; 

) TearOf fMenuGlobals, *TearOf fMGlobalsPtr, **TearOffMGlo- 
balsHdl; 


There must be one of these structures for each of the menus 
that will be torn off. The TearOffMenuGlobals structure contains 
eight elements: 

drawMenuProc: A function pointer to a Pascal-type pro- 
cedure which draws the contents of the menu in global coordi- 
nates within the WMgrPort. 

finditemProc: A function pointer to a Pascal-type proce- 
dure which returns the number of the menu item where the mouse 
is Currently located. 

hiliteltemProc: A function pointer to a Pascal-type proce- 
dure which highlights or unhighlights a given menu item. 

environment: A pointer toa SysEnvRec used to test if the 
64K ROMS are present. 

paletteWindow: A WindowPtr used to calculate 
menuWidth, menuHeight, and the structure boundary from the 
window’s portRect. 

currentitem: A short int containing the number of the 
currently highlighted menu item. 
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position: A Point passed to the application from Теа- 
rOffMDEF indicating the top, left point, in global coordinates, of 
a torn-off menu. 

ItemHilited: A Boolean used internally by TearOffMDEF. 

Allof these elements, except position and itemHilited, must 
be initialized by the application before a tear-off menu is inserted 
into the menu list. 

Remember, the application is completely responsible for the 
appearance of the menu. A set of the three following procedures 
must be declared in the application for each tear-off menu: 

pascal void DrawMenuProc(destRect ) 

Rect *destRect; /* The menu rectangle in the current 


grefPort where the application should 
draw the menu. */ 


pascal short FindItemProc(mousePt) 

Point mousePt; /% The point in which the mouse is 
currently located, relative to the 
top, left of the menu rectangle. */ 


/* This routine must return the 
number of the menu item where the 
mouse is currently located. */ 


pascal void HiliteItemProcC(destRect, item, hilite) 

Rect *destRect; /* The menu rectangle in the current 

grafPort. */ 

/* The number of the item to be 

highlighted or unhighlighted. */ 

Boolean hilite; /* А flag that determines the state 
of the highlighting. True means 
highlight the item, false means 
unhighlight. */ 


short item; 


Inside TearOffMDEF 

If you want to take a closer look at our TearOffMDEF code, 
pay particular attention to a few points. 

We must refer to QuickDraw's globals in a peculiar fashion. 
Why? Since we're not an application, we can't call InitGraf() to 
initialize any compiler offsets to address register 5. We have to 
set up a pointer to these globals via the low-memory location 
CurrentA5 and refer to them by explicit dereference of that 
pointer. A bit inconvenient, but it means that when you want to 
draw in white it doesn’t come out looking like chicken scratches. 

When we track the mouse to correctly highlight items, we 
make sure the ROM will correctly flash the item when the mouse 
is released. Getting the menu to flash is more than just making the 
algorithm in your code function in a certain way. Specifically, 
you must insert enough fake items in the MENU resource so that 
the Menu Manager thinks the item you chose exists when it calls 
CountMItemsQ, otherwise it won't flash it. 

Furthermore, our code expects the Menu Manager to tell us 
the mouse is in position (0, 0) when it's trying to flash the item. 
An undocumented feature, true, but it hasn't changed yet. This 
doesn't happen if the menu is called via PopUpMenuSelectQ) 
(and no, we don't know why), but since we don't think pop-up 
menus should be torn off, we don't even worry about it. 

And how does the menu tear off? If the Menu Manager calls 
TearOffMDEF and the mouse is outside the menu rectangle by 
more than 15 pixels, ош DragMenu( routine is called. Simple. 
DragMenu() follows the mouse around (just like DragGrayRgn() 
in the ROM) with a gray outline of the menu. Notice that the 
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outline doesn't flash like HyperCard or the new MacPaint. 
DragMenu( retains control until the mouse button is released or 
the mouse returns to the menu rectangle or menu bar. If the mouse 
returns the code returns. If the mouse button is released outside 
the menu rectangle, we set the item selected to -1 and place the 
top, left corner of where the palette should be drawn in the 
position field of the appropriate TearOffMenuGlobals structure. 


Using TearOffMDEF in Your Application 

If you intend to use TearOffMDEF, you're going to have to 
move the MDEF code resource file into your application. If 
you're using LightspeedC, just paste it into the common resource 
file with ResEdit. If you're translating this to MPW C, then you 
can use Rez to put it all together at once. 

By the way, there is one very important thing to remember 
when you create an MDEF (or another kind of xDEF), always 
make sure it's resource flags are set to non-purgeable. Why? The 
ROM doesn't like it when acode resource gets purged at runtime. 
Any heap compaction can force this to happen. 

Also, there's another REAL thrill you need to work around 
if you compile this MDEF. It's a conflict with LightspeedC and 
our favorite ROM. As we all know, the Menu Manager passes the 
menu item to be manipulated to an MDEF by address. Usually the 
item is located on the stack. But when the Menu Manager 
repeatedly calls your code to cause a menu item to flash, it passes 
ToolScratch as the address of the item. Why? Who knows. The 
conflict occurs because LightspeedC stores the address of the 
separate code resource (in this case, the MDEF) in ToolScratch 
as soon as that code is called by the ROM. Why? This allows a 
programmer (who doesn't want to use in-line assembly) to find 
out exactly where the code exists in memory by simply looking 
in ToolScratch. A perfectly legal and very clever use of that low- 
memory global. 

Believe it or not, the ROM's use of ToolScratch is definitely 
Apple's problem. When we told Paul Mercer in Apple Tech 
Support about this, he even filed an official bug report. Is that 
service or what? | | 

То work around the problem, Michael Kahl, the author of 
LightspeedC, says he may change his glue for code resources in 
the soon-to-be-released version 3.0 of his compiler. Until then, 
both Apple and Mike suggest patching the MDEF after it's 
compiled. A real pain we know, but use ResEdit or FEdit to 
change hex string '21c809ce' at hex offset 14 in the MDEF 
resource to ‘4e714e71.’ This substitutes two “пор” instructions 
for a ‘тоуе.1 a0, ToolScratch.' 

Mike Kahl says you can also modify your copy of the 
compiler so it never generates these instructions when the code 
resource is compiled. The glue in versions 2.13 and 2.15 is 
located in code resource number 11, also at hex offset 14. The 
patch is identical. Remember, do it to a copy. 

Let us repeat that the segment in which your application's 
procedures are declared must remain locked at runtime, the ROM 
will not chase your procedures around. Place it in your main 
segment and you shouldn't have to worry. 

Remember the application must move the palette window 
and make it visible when MenuSelect() returns -1 from a tear-off 
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menu. We'll explain how we keep the little beggars floating in 
just a bit. 

Also, when the user moves the palette or clicks the mouse 
inside it, some response is necessary. If you want to emulate the 
Menu Manager and its drawing, finding, and highlighting of 
menus, your application must do this itself for floating palettes. 
We went the easy route and just used the same three routines 
again that are called by the MDEF. They're already in the 
application code, right? We're lazy and we highly recommend 
this lack of effort. 


Inside PaletteWDEF 

Our PaletteWDEF is pretty straightforward. It creates win- 
dows almost identical to those in HyperCard or the new 
MacPaint. The main difference being PaletteWDEF will respond 
to a Window Manager request to unhighlight the title bar. Also, 
the drop shadow created by PaletteWDEF more closely matches 
a menu's drop shadow than an ordinary window. 

The only real tricky thing in the code is where we create the 
pattern to fill the title bar. Why? Windows are drawn into the 
Window Manager port. The origin is always in the top, left corner 
of the screen. Patterns are always aligned to the origin. Depend- 
ing on where the top, left corner of the window will be, the pattern 
may not align when the window is drawn. 

Apple's standard WDEF, originally written by Andy 
Hertzfield, uses arather undocumented QuickDraw global called 
patAlign to make sure everything looks correct. If you look at the 
interface files to most high-level language compilers available 
for the Macintosh, you won't even find this field defined. It is in 
the MPW assembler equates though. 

Even though we defined our own QuickDraw structure, we 
decided not to use a global not even discussed in any Apple 
documentation that we could find. Instead, we create the pattern 
on the fly. It’s a very regular pattern, each horizontal line contains 
either 55, 55, 55 etc. or AA, AA, AA etc. After we wrote this 
‘hack’ we decided to disassemble HyperCard and see how Bill 
Atkinson did it. You guessed it, the same way. 


Keeping Palettes Above Documents 

The first thing you need to know about palettes to keep them 
floating is where they are and where the top-most document is. 
Specifically, where in the window list. Window list? Yes, the 
Window Manager keeps a linked list of all windows beginning in 
a low-memory global called WindowList. It points to the first 
window and it's very handy. In fact FrontWindow(, in the Mac 
ROM, steps through this list to find the top-most visible window 
and then returns a pointer to it. 

We wrote our own version of FrontWindow( called Lo- 
cateWindows() It doesn't return a pointer — instead it initializes 
four global variables called TopWindow, TopPalette, Bottom- 
Palette and TopDocument It's called once during the beginning 
of our event loop. But why do we need to know all this? 

If your application is only going to use one document 
window, then perhaps you can keep a pointer to it in a global 
variable and test to see if it's visible or not. And if you only have 
one palette, or a fixed number of palettes, you can maintain a 


© The Definitive MacTutor, Vol. 4 


series of pointers to them. You can even create all of these 
windows at once so you know what order they're in. Right? 

Well, what if somebody uses QuicKeys or the public domain 
Windows DA to change the order of the windows? And if you 
want your palettes to have a dynamic order or you need more than 
one document then you're going to have to keep track of a few 
things. These four globals are the minimum you need to know 
about the window list. 

When a document window is created it can appear behind the 
bottom palette only if you know which window is the bottom 
palette. Look at our example code carefully and notice the care 
and feeding of these globals. Every operation to keep palettes 
floating above documents depends on LocateWindows(). 

And initializing these four globals isn't the only thing 
LocateWindows() does. If it finds a non-application window 
between the palettes and top-most document, it moves that 
window. If it finds a document above one of the palettes, it moves 
it below the bottom palette. 

Usually FrontWindow( is also called by an application to 
tell if that application is active. We wrote a small function called 
ActiveWindow(), to which we pass a window pointer and test it 
to make sure it is either the TopDocument or one of the palettes. 

Now the hard part. 

Normally if you click ina window, it's brought in front of all 
other windows. SelectWindow( is always used to do this. But 
you can't call SelectWindow() for a document if a palette is 
visible. How do you keep it from being brought to the front? Use 
SendBehind() instead. Right. Just send the document behind the 
BottomPalette. 

Look carefully at our code to see how we did this in a 
function called DoSelectWindow(). You'll also notice that we 
use two low-level Window Manager routines called Calc VisBe- 
hind() and PaintOne() after we move the document. Why? If a 
window is sent behind a window that is above it, the Window 
Manager must redraw parts of the affected windows. We speed 
up this process by calculating the minimum area to be redrawn. 
See "Inside Macintosh Volume I," page 286, for details on this 
process. 

Another ROM call to avoid is DragWindow(). Annoyingly, 
DragWindow() will always bring a window to the front if the 
window pointer passed to it is not already in front. You can hold 
the command key down while you drag a window to keep this 
from happening, but there's no clean way to ‘depress’ this key 
from within your code. Instead, look at DoDragWindow() and 
Drag() in our code. We had to completely rewrite this ROM 
routine. DoDragWindow() handles all of the logic of when and 
where to drag, and Drag() actually moves an outline of the 
window around the screen. 

Are you seeing a pattern yet? Right. To suspend palettes 
above documents, never call a function which will directly move 
a document to the front if a palette is visible. 

Still, problems with window highlighting, the appearance of 
controls, and the grow icon can occur while doing our juggling 
act with the Window Manager. Basically, you can't depend on 
the ROM to always activate or deactivate a document — it's not 
really the front window. “Inside Macintosh Volume 1,” page 280 
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contains a discussion of two low-memory variables called Си- 
rActivate and CurDeactive. Clever manipulation of these globals 
can direct the Event and Window Managers to activate or 
deactivate something other than the front window. It's all legal 
and it works just fine. | 

But Apple may change these low-memory globals one of 
these days. With the advent of MultiFinder and the Layer 
Manager, the Window Manager has been changing. Just to be 
safe, we’ ve developed a different technique to do this that doesn’t 
write to these locations. It'S a bit of a pain, but it works. 
Essentially, we must explicitly highlight windows, activate 
controls, and redraw grow icons when documents are moved 
within the window list. Take a look at two of our routines called 
ActivateDocument() and HiliteUserWindows() — they're pretty 
straightforward. 

Remember, the whole process of floating a palette is a 
charade. First you fool the ROM, and then you can fool the user. 


How to Read the Code 

First we'd like to acknowledged our debt to the folks in 
Apple Tech Support for providing us with some helpful clues. 
Also, many thanks to Mike Kahl and the rest of the gang on 
Compuserve's LVTForum, home to many LightspeedC and 
Pascal nerds (Are you a THINKer? Just type GO THINK when 
you're on CIS). And finally, thanks to David Smith for believing 
we could pull it off. 

We've tried to give as complete an example as possible. 
Although our code can be used almost like libraries, the whole 
idea is to share needed information with the rest of the Mac 
community. And to show off, of course. If you read this and come 
up with some better solutions or (horror!) bugs, please let us 
know. 

You might have already noticed that we wrote all of our code 
in C. Why? Sometimes we want to send the wrong type some- 
where. Of course, we don’t recommend this, we just do it. At least 
we didn't use any in-line assembly. 

Actually, we designed the code to be easily translated into 
Pascal. Too bad if you're using COBOL though. We didn't use 
too many special C *tricks' that aren't obvious anyway. If you 
look at the application code, you may notice that it's rather 
repetitive in sections that deal with updating or drawing into 
palette windows. In our own project we're developing we use 
arrays of function pointers indexed with a palette's ID number 
(stored in the window refCon field) to make everything much 
shorter and more elegant. We thought this would probably 
confuse Pascal programmers though. 

Although we wrote this in LightspeedC, the resources are 
listed in MPW Rez format. Sorry, but we never use RMaker. It's 
just not powerful enough. 

This whole thing is a monster. Our advice is buy the source 
code disk from David. It's actually contained in three Light- 
speedC project files. Here's a breakdown: 

TearOffMDEF.project 

TearOffMDEF.c The menu definition. 
PaletteWDEF.project 
(No need to link with MacTraps) 
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PaletteWDEF.c The window definition. 

TearOffPalette.project 

(All of these go in the main segment) 

TearOffPalette.c The main program. 

Interface.c Adjusts the use of color at 
runtime. 

Error.c Error and grow zone function. 

Window.c Creation and updating of win- 
dows. 

Dialog.c About dialog and utilities. 

Menu.c The routines called by the MDEF. 

Palette.c The code that floats the palettes. 


(Place this in a separate segment) 
Initialize.c Initialization and creation of 


palettes. 


(The include files are used by all of the sources) 
Constants.h include files and our definitions. 
Variables.h Global variables. 


(MPW Rez format resource file) 
TearOffPalette.project.r 


(Move the MDEF and WDEF into this file with ResEdit) 
TearOffPalette.project.rsrc 


Finally, if you program in C, you had better try to maintain 
a style of some kind. If you don’t, nobody will ever be able to 
make heads or tails of your code, including you. We’ ve tried to 
use classic indentation, but we'd like toclarify our nomenclature. 


FunctionNameQ) Always an initial capital. 

GlobalVariable Just like the functions. 

localVariable The first letter is always lower case. 

A CONSTANT All capitals, underscores dividing 
words. 


Of course many of Apple’s globals and constants don’t 
follow our rules. Oh well. It might not make sense to you, but at 
least we’re consistent. On to the code! 

/* TEAROFF PALETTE 


version 1.0 
by Don Melton end Mike Ritter 


Copyright 9 1987, 1988 by Impulse Technologies, 
Inc., 811 rights reserved. 


Filename: Constants.h 

Font: Courier, 9 point 

Tab setting: 2 

Compiler: LightspeedC 2. 15 

Project type: APPL 

Creator: TOPD */ 
/*——— INCLUDE DEFINITIONS */ 


include “Color .h” 
include "ColorToolbox.h^ 
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t include 
tinclude 
include 
t include 
* include 
t include 
* include 
t include 
8 include 
t include 
8 include 
* include 
* include 
* include 
* include 
* include 
t include 
* include 


/* 


*ControlMgr .h^ 
*DeskMgr .h^ 
“DialogMgr .h” 
*EventMgr .h” 
*FileMgr.h^ 
*FontMgr .h^ 
“MacTypes .h^ 
*MemoryMgr . h^ 
*MenuMgr . h^ 
*0SUt il.h^ 
“PackageMor .h^ 
“Quickdraw.h” 
*ResourceMgr .h^ 
*SegnentLdr .h^ 
*StdF i lePkg.h^ 
*TextEdit.h^ 
*ToolboxUtil.h^ 
*WindowMgr .h^ 


SYSTEM CONSTANTS */ 


"define nil 0 
8def ine NULL 0 
"define zoomDocProc 8 
"define zoomNoGrow 12 


/%---------------ҒҺУІРОММЕНТ %/ 
def ine VERSION.REQUESTED 1 


"def ine WAIT.NEXT EVENT. TRAP.NUMBER 0x60 
"def ine UNIMPLEMENTED. TRAP NUMBER 0x9f 


/%----------------МЕМҮ */ 
"def ine MEMORY. BUFFER- SIZE 0х8000 /* 32K. */ 


/* 


VENTS */ 


"def ine SLEEP. DURATION 50 


/%----------------ЧІК00ОН5 */ 


define VISIBLE true 

def ine NOT_VISIBLE false 

def ine BRING_TO_FRONT CWindowPtr) -1 
Qtdef ine SEND. BEHIND nil 

def ine GO_AWAY_BOX true 

def ine NO. GO. AWAY. BOX false 

8dgef ine NO. REFCON nil 


[5 — PALETTES */ 


enum ( 


TOOL. PALETTE, 
PATTERN. PALETTE, 
COLOR PALETTE, 
DOCUMENT. WINDOW 


д 


"def ine PALETTE_COUNT З 


"def ine PALETTE. WDEF 10 128 
"define TEAROFF_MDEF_ID 128 


/* 


TEAROFF MENU GLOBALS */ 


typedef struct TearOffMenuGlobals ( 
void (*drewMenuProc2C); 
short (*findItemProc)(); 
void C*hiliteItemProc2C); 
SysEnvRec *environment; 
WindowPtr paletteWindow; 
Point position; 
short currentItem; 
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Boolean itemHilited; 
) TearOffMenuGlobals, *TearOffMGlobalsPtr, **TearOffMGlobal- 
sHdl; 


"def ine TEAR- OFF. МЕМ) 61 0ВА15. ТҮРЕ ‘TOMG’ 
/J*+——— Ñs — TL PALETTE %/ 


"def ine TOOLS_ACROSS 4 

"define TOOLS_DOWN 4 

"define TOOL COUNT CCTOOLS_ACROSS ж TOOLS DOWN) + 1) 
"define DEFAULT. TOOL 4 

"define TOOL PICT.ID 128 


/х---------------ҒАТТЕРМ PALETTE */ 


def ine PATTERNS. ACROSS 8 
"def ine PATTERNS. DOWN 8 


8def ine PATTERN. COUNT CCPATTERNS- ACROSS 
ж PATTERNS-DOWND + 1) 


"def ine PATTERNITEM WIDTH 16 
"дег ine РАТТЕКМ_ТТЕМ_НЕТСНТ 16 


#def ine DEFAULT. PATTERN 1 
"def ine PATTERNS_ID 128 


%---------------<0(08 PALETTE */ 


"def ine COLORS. ACROSS 16 

"define COLORS.DOWN 16 

"define COLOR.COUNT CCCOLORS.ACROSS * COLORS_DOWN) + 1) 
"define COLOR. ITEM WIDTH 8 

"def ine COLOR ITEM. HEIGHT 8 

"define DEFAULT. COLOR 1 


%----------------20ОМЕМТ5 */ 


"def ine ТІТІЕ ВАК. НЕІОНТ 18 

#def ine SCROLL BAR SIZE 16 

"def ine SCREEN. MARGIN 4 

"define MIN. WINDOW. WIDTH 80 

"def ine MIN. WINDOW.HEIGHT 80 

“def ine HORIZONTAL_WINDOW_OFFSET 8 
"def ine VERTICAL. WINDOW. OFFSET 8 
"def ine DOCUMENT. COUNT 8 

#def ine DOCUMENT. TITLE. STRING-ID 128 


%---------------“ЕМ/5 */ 


enum ( 
APPLE. MENU. INDEX, 
ҒЦЕ МЕМ). INDEX, 
ЕОІТ. МЕМ). INDEX, 
TOOL. МЕМ). INDEX, 
PATTERN. MENU. INDEX , 
COLOR. MENU. INDEX 


enum ( 
APPLE_MENU_ID = 128, 
FILE_MENU_ID, 
EDIT_MENU_ID, 
TOOL MENU. ID, 
РАТТЕЕМ. МЕМ). 10, 
COLOR. MENU. ID 


"def ine MENU_COUNT 6 
"def ine MENU_ID_OFFSET APPLE. МЕМ) 10 


Sdef ine TEAR-OFF.MARGIN 15 
def ine МОУЕ РА ЕТТЕ. ІТЕМ (-1) 
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/%-----------------АРРІЕ MENU ITEMS */ 
"def ine ABOUT ITEM 1 
[*—— EDIT MENU ITEMS */ 


enum ( 
UNDO_ITEM = 1, 
CUT ITEM = 3, 
COPY_ITEM, 
PASTE_ITEM, 
CLEAR_I TEM 


) 


/х%-----------------ҒДЕ MENU ITEMS */ 


enum ( 
NEW.ITEM = 1, 
CLOSE_ITEM = 3, 
QUIT_ITEM = 5 


9 


/*——— R —— A B0UT DIALOG */ 
"def ine ABOUT.DIALOG.ID 128 
/%---------------ТЕАЮКОҒҒ PALETTE 


version 1.0 
by Don Melton and Mike Ritter 


Copyright (621987, 1988 by Impulse Technologies, 
Inc., 811 rights reserved. 


Filename: Veriebles.h 
Font: Courier, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2.15 
Project type: APPL 

Creator: TOPD */ 


/%---------------“ІОВЛА/ VARIABLE DECLARATIONS */ 
"ifdef GLOBAL. VARIABLES 


SysEnvRec Environment; 
EventRecord Event; 


GOHendle MaxDevice; 
MenuHandle Menus (MENU. COUNT J; 


TeerOffMGlobalsHd] TeerOffs(PALETTE COUNT 1; 
WindowPtr Pelettes(PALETTE-COUNT 1; 


WindowPtr TopWindow; 
WindowPtr TopPalette; 
WindowPtr BottomPalette; 
WindowPtr TopDocument; 


Rect ToolRects (TOOL COUNT Ј; 

Rect PetternRects [IPATTERN. COUNT ]; 
Rect ColorRects{COLOR_COUNT J; 
short PositionCounter ; 

long Sleep; 

Boolean ClosingAl1; 

Boolean Quitting; 

Boolean Finished; 

Boolean OutOf Memory; 

Boolean WNEIsImplemented; 
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Boolean MouseInMenu; 


Boolean ColorMenuVisible; 
Boolean PalettesVisible[PALETTE. COUNT); 


Handle MemoryBuf fer; 
telse 


extern SysEnvRec Environment; 
extern EventRecord Event; 


extern GDHandle MaxDevice; 
extern MenuHandle Menus (MENU. .COUNT 1; 


extern TearOffMGlobalsHd! TearOffs[PALETTE. COUNT); 
extern WindowPtr Palettes [PALETTE COUNT ); 


extern WindowPtr TopWindow; 
extern WindowPtr TopPalette; 
extern WindowPtr BottomPalette; 
extern WindowPtr TopDocument; 


extern Rect ToolRects([ TOOL COUNT J; 
extern Rect PetternRects [PATTERN. COUNT ); 
extern Rect ColorRects (COLOR..COUNT ]; 


extern short PositionCounter; 
extern long Sleep; 
extern Boolean ClosingA11; 


extern Boolean Quitting; 
extern Boolean Finished; 


extern Boolean OutOfMemory; 
extern Boolean OutOfMemory; 
extern Boolean WNEIsImplemented; 
extern Boolean MouseInMenu; 


extern Boolean ColorMenuVisible; 
extern Boolean PalettesVisible[PALETTE. COUNT 1; 


extern Handle MemoryBuf fer ; 
endif 
/*—— IN EAROFF PALETTE 


version 1.0 
bu Don Melton and Mike Ritter 


Copuright (C)1987, 1988 bu Impulse Technologies, 
Inc., all rights reserved. 


Filename: TearOffPalette.c 
Font: Courier, 9 point 
Tab setting: 2 

Compiler: LightspeedC 2.15 
Project type: APPL 

Creator: TOPD 

Segment: Main 


—— ЕЗСКРИОН 


TearOffPalette is a demonstration of a very portable 
method of implementing tear-off menus and floating 
palettes. This technique uses external MDEF and WDEF code 
resources. The MDEF communicates with the application via 
а TearOffMenuGlobals structure іп а TOMG resource. 


See TearOffMDEF.c for an explanation of the TearOff- 
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MenuGlobals structure and the routines an application must 


contain to use TearOffMDEF. 


See PaletteWDEF.c for ап explanation of the behavior and 


use of PaletteWDEF. 


TearOffPalette is designed to keep palettes floating 
above documents without directly writing to low-memory 
Window Manager globals. 


А Color menu and palette will be displayed when Color 
QuickDraw is present and the depth of the screen allows 
256 colors. 


Under MultiFinder end at any Suspend or Resume event, 
TearOffPalette will hide or show all visible palettes. 


IMPORTANT! TearOffPalette.project.rsrc must contain the 
TearOffMDEF and PaletteWDEF resources created by compiling 


their respective source files. */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS %/ 


"def ine GLOBAL. VARIABLES 


* include “Constants.h’ 
include "Variables.h"^ 


[E — EXTERNAL FUNCTION DECLARATIONS */ 


extern void Initialize(); /* Initialize.c */ 


extern void DoAbout(); /* Dialog.c */ 


extern void AdjustInterface(); /* Interface.c */ 
/* Palette.c */ 
/* Palette.c */ 
/* Palette.c */ 
/* Palette.c */ 
/* Palette.c */ 


extern void LocateWindowsC); 
extern short ActiveWindow(); 
extern void DoSelectWindow(); 
extern void DoDragWindow(); 
extern void HiliteUserWindowsC); 


extern void ActivateDocument(); 
extern void UpdateDocument C); 
extern void SizeDocument(); 
extern void UpdatePalette(); 
extern void NewDocument(); 
extern void CloseDocument(); 


/* Window.c */ 

/* Window.c */ 
/* Window.c */ 

/* Window.c */ 

/* Window.c */ 

/* Window.c */ 


extern pascal short FindToolItemC; /* Menu.c */ 
extern pascal void HiliteToolItemC); /* Menu.c */ 
extern pascal short FindPatternItem(); /% Menu.c */ 
extern pascal void HilitePatternItem(); /* Menu.c */ 
extern pascal short FindColorItemC; /* Menu.c */ 
extern pascal void HiliteColorItem(); /% Menu.c */ 
extern void MovePalette(); /* Menu.c */ 


/х%--------------ҒОЮКАКО FUNCTION DECLARATIONS */ 


void ПоЕуел (С); 

void MouseDownEvent(); 
void KeyEvent(); 

void ActivateEvent(); 
void UpdateEvent(); 

void SuspendResumeEvent(); 
void MenuEvent(); 


void AppleMenu(C); 
void FileMenu(); 
void EditMenuC); 
void ToolMenuC); 
void PatternMenuC ); 
void ColorMenu(); 
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void ContentEvent¢); 
void GrowEvent(); 
void InvalGrow(); 
void CloseEvent(); 


/*—————————————ТЕАВ0ЕЕ PALETTE */ 
main() ( 


InitializeC); 
UnloadSeg( Initialize); 


DoAbout(); 


whileCC!Finished) && C!OutOfMemory)) ( 
Adjust Interface); 
DoEvent(); 


) 
%--------------00 EVENT */ 


void DoEvent() ( 
Boolean result; 


ifCWNEIsImplemented) ( 
result = WaitNextEventCeveryEvent, &Event, Sleep, 
nil); 


else ( 
SustemTask(); 
result = GetNextEventCeveryEvent, &Event); 


/* Find all application windows in the window list, 
end adjust their order if necessary. 

IMPORTANT! Always call LocateWindows() after getting 
the event. */ 

LocateWindowsC); 

if(result) ( 

switch(Event.what) ( 
case mouseDown: 


if(!(ClosingA11 || Quitting)) ( 
MouseDownEvent(); 


break; 


case keyDown: 
case autokey: 


ifC!CClosingAl] || Quitting)) ( 
KeyEvent(); 


break; 


case updateEvt: 
UpdateEvent(); 
break; 


case activateEvt: 
ActivateEvent(); 
break; 


case app4Evt: 
SuspendResumeEvent C); 


else ( 


if((ClosingA1] || Quitting) && CEvent.what 
== nullEvent)) ( 
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) 


/* И the application is quitting or the option 
key wes held down when closing а window, the 

top visible window is closed during each pass 
through the event loop until а11 windows аге 

closed. */ 


if(TopWindow != nil) ( 
CloseEvent(TopWindow); 


else ( 
ClosingAll = false; 


if(Quitting) ( 
Finished = true; 


) 


/%----------------М0ОИС5ЕООЯМ EVENT 


AcitiveWindow() replaces most traditional calls to 


FrontWindow(). All use of SelectWindow() and DragWindow() 
is replaced by calls to DoSelectWindow() and DoDragWin- 
dow(). This ensures mouseDown events in application 
windows handle floating palettes properly. */ 


void MouseDownEvent() ( 
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WindowPtr whichWindow; 
short whichPart; 


MouseInMenu = false; 
whichPert = FindWindowCEvent where, &whichWindow); 
switch(whichPert) ( 


case inMenuBar: 
MouseInMenu = true; 
MenuEvent(MenuSe lectCEvent . where); 
break; 


case inSusWindow: 
SustemClick(&Event, whichWindow); 
break; 


case inContent: 
if(!Activewindow(whichWindow)) ( 
DoSelectWindow(whichWindow); 


else ( 
ContentEvent(whichWindow); 


break; 
case inDrag: 
DoDragWindow(whichWindow); 
break; 
case inGrow: 
if(!ActiveWindow(whichWindow)) ( 
DoSelectWindow(whichWindow); 


else ( 
GrowEvent(whichWindow); 


break; 
case inGoAway: 
if(!Activewindow(whichWindow)) ( 
DoSelectWindow(whichWindow); 


else ( 


if (TrackGoAwau(whichWindow, Event.where)) ( 
CloseEvent(whichWindow); 


break; 


case inZoomIn: 
case inZoom0ut: 
if (TrackBoxCwhichWindow, Event.where, 
whichPert)) ( 
SetPor tCwhichWindow); 
EraseRect(&whichW indow-) por tRect 2; 
ZoomWindow(whichWindow, whichPart, false); 
SizeDocument Cwh ichWindow); 


) 
) 


[$—————————XEYDOWN AND AUTOKEY EVENT */ 


void KeuEvent() ( 
char whichChar; 


whichChar = Event.message & charCodeMask; 
ifCCEvent.modif iers & cmdKey) != Ø) ( 


ifCEvent.what != eutoKey) ( 
MenuEventCMenuKeyCwh i chChar 22; 


) 
) 


/%----------------АС(ГТІУАТЕ EVENT */ 


void ActivateEvent() ( 
WindowPtr whichWindow; 


/* Ensure all application windows are hilited сог- 
rectly. */ 

HiliteUserWindowsC); 

whichWindow = CWindowPtr) Event.message; 


if CCCWindowPeek) whichWindow)->refCon 
|= DOCUMENT_WINDOW) ( 
/* Pess activate event from palette to 
TopDocument. */ 
whichWindow = TopDocument; 


) 
if(whichWindow != nil) ( 
/* Ensure document window’s controls are properly 
visible and hilited. */ 
ActivateDocumentCwhichWindow, Event modif iers 
& activeF lag); 
) 


/%----------------МРАТЕ EVENT */ 


void UpdateEvent() ( 
WindowPtr whichWindow; 


whichWindow = CWindowPtr) Event.message; 
SetPor t wh ichWindow); 
BeginUpdateCwhichWindow?; 
if(((WindowPeek) whichWindow)->refCon 
== DOCUMENT_WINDOW) ( 
UpdateDocument (wh i chW indow ); 


else ( 
UpdatePalette(whichWindow); 
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DrewControls(whichWindow); 
DrewGrowIcon(whichWindow); 


EndUpdete(CwhichWindow); 


/----------5/5РЕМ) /RESUME EVENT 


Hide 811 palettes when the application is not the active 
lager. This leaves the screen much less cluttered. */ 


void SuspendResumeEvent() ( 
short index; 


forCindex = Ø; index < PALETTE_COUNT; index**) ( 


if (CEvent.message & 1) == Ø) ( 
PalettesVisible[index] = C(WindowPeek) 
Palettes[ index]? visible; 
ShowHideCPalettes[index], false); 


else ( 
ShowHide(Palettes[ index], 
PalettesVisible[index1); 
PalettesVisible[index] = false; 


LoceteWindowsC); 
HiliteUserWindowsC); 


if CCCCWindowPeek) TopWindow)-— windowKind == userKind) 
&& CTopDocument != пі1)) ( 
/* Ensure the TopDocument’s controls are properly 
visible and unhilited. */ 
ActivateDocument(TopDocument, Event.message & 1); 


) 
=— —————MENU AND COMMAND KEY EVENT */ 


void MenuEventCmenuCho ice ) 
ong nenuChoice; 


short whichMenu; 
short whichItem; 


/* HiWordCmenuChoice). */ 
whichMenu = menuChoice >> 16; 

/* LoWord(menuChoice). */ 
whichItem = menuChoice & OxFFFF; 


Switch(whichMenu) ( 


case APPLE. МЕМ) ID: 
AppleMenuCwhichItem); 
break; 


case FILE_MENU_ID: 
FileMenuCwhichI tem); 
break; 


cese EDIT. MENU. ID: 
EditMenu(whichItem); 
break; 


сазе TOOL. MENU. ID: 
ToolMenuCwhichItem); 
break; 


case PATTERN. МЕМ) 10: 


PatternMenuCwhichI tem); 
bresk; 
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case COLOR_MENU_ID: 
ColorMenuCwhichI tem); 


HiliteMenu(0); 


/x——— SELECT APPLE MENU ITEM */ 


void AppleMenuCwhichItem) 
short whichItem; 


Str255 daName; 


ifCwhichI tem == ABOUT_ITEM) ( 
DoAbout(); 


else ( 
GetItemCMenus [APPLE MENULINDEX], whichI tem, 
&daName ); 
/* Ignore the result returned by the ROM. */ 
(void?) OpenDeskAcc(&daName ); 


) 
/*— SELECT FILE MENU ITEM %/ 


void FileMenuCwhichItem) 
short whichItem; 


switch(whichItem) ( 


case NEW. ITEM: 
NewDocunent(); 
breek; 


case CLOSE. ITEM: 


CloseEventCTopDocument ); 
break; 


case QUIT. ITEM: 
Quitting = true; 
Sleep = 0; 
) 
/%---------------5ЕЕСТ EDIT MENU ITEM */ 


void EditMenuCwhichI tem) 
ra whichI tem; 


(void) SystemEditCwhichI tem - 1); 


/%---------------5ИЕСТ TOOL MENU ITEM */ 


void ToolMenuCwhichI tem) 
short whichI tem; 


WindowPtr paletteWindow; 
paletteWindow = Palettes[TOOL. PALETTE]; 


ifCwhichI tem == MOVE PALETTE ITEM) ( 
/* The menu has been torn off. */ 
MovePaletteCpaletteWindow, 
(*Tear Of fs [TOOL PALETTEJ2— position); 


else ( 


if CwhichI tem 
l= (*Tear Of fs{TOOL_PALETTE]) 
-»currentItem) ( 
SetPortCPalettes[ TOOL. PALETTE 1); 
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/* Unhilte the old item. */ 

HiliteToolItenC&paletteWindow-?portRect, 
(*TearOf fsC TOOL PALETTE )->currentI tem, 
false); 

/* Hilite the new item. */ 

HiliteToolI temC&paletteW indow-> por tRect, 
whichItem, true); 


(*Tear Of fs(COLOR_PALETTE])->currentI tem, 
false); 
/* Hilite the new item. */ 
HiliteColorItemC&paletteWindow- portRect, 
whichItem, true); 


/* Set currentItem equal to the new item. */ 
(*TearOf f SLCOLOR PALETTE J2-? currentItem = 


/* Set currentItem equal to the new item. */ whichI tem; 
(*TearOf fs{TOOL_PALETTE])->currentItem 
= whichI tem; ) 
| ) ) 
) %-------------:СОҺТЕМТ EVENT */ 
/х----------------ОИЕСТ PATTERN MENU ITEM */ void ContentEventCwhichWindow) 


void PatternMenuCwhichItem) 
short whichItem; 


WindowPtr paletteWindow; 
paletteWindow = Palettes[PATTERN. PALETTE ]; 


if(whichltem == MOVE_PALETTE_ITEM) ( 
/* The menu has been torn off. */ 
MovePalette(paletteWindow, 
(*Tear Of fs(PATTERN_PALETTE 12)? position); 


else ( 


if CwhichI tem 
Is (*TearOf fsSIPATTERN-PALETTE 12 
-currentItem) ( 
SetPort(Palettes(PATTERN_PALETTE)); 


/* Unhilte the old item. */ 
HilitePatternItemC&paletteWindow-?portRect, 
(*Tear Of fs [PATTERN PALETTE 1) 
-)currentItem, false); 
/* Hilite the new item. */ 
HilitePatternItenC&paletteWindow-?portRect, 
whichItem, true); 


/* Set currentItem equal to the new item. */ 
(*TearOf fs [РАТТЕКМ_РАСЕТТЕ ] )-› currentItem = 
whichItem; 


) 
) 


м — — ——-SELECT COLOR MENU ITEM */ 


void ColorMenu(whichItem) 
short whichItem; 


WindowPtr paletteWindow; 
paletteWindow = Pelettes [COLOR PALETTE 1; 


if (whichItem == MOVE PALETTE. ITEM) ( 
/* The menu has been torn off. */ 
MovePaletteCpaletteWindow, 
а ыы 


else ( 


if CwhichI tem 
Iz (*TearOf fs(COLOR_PALETTE]) 
-)currentItem) ( 
SetPortCPalettes LCCOLOR-PALETTE 12; 


/* Unhilte the old item. */ 
HiliteColorItemC&paletteWindow-?portRect, 
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WindowPtr whichWindow; 
( 


Point mousePt; 
short item; 


SetPor tCwhichWindow); 


mousePt = Event .where; 
GlobalToLocal(&mousePt); 


/* Use the window’s refCon to determine what type of 


epplication window received the event. */ 


switch(((WindowPeek) whichWindow)- refCon) ( 


case TOOL PALETTE: 
item = FindToolI temCmousePt ); 


if Citem 

Iz (*TearOf fs TOOL PALETTE) 
-)currentItem) ( 

/* Unhilte the old item. */ 

HiliteToolItenC&whichWindow-?portRect, 
(*TearOf fsL[ TOOL PALETTE ])-› 

currentItem, false); 

/* Hilite the new item. */ 

HiliteToolI temC&whichWindow->portRect, item, 
true); 


/* Set currentI tem equal to the new item. */ 
(*Tear Of f sL[TOOL. PALETTE ])-> current! tem 
= item; 
) 
break; 


case PATTERN. PALETTE : 
item = FindPetternItem(mousePt); 


if Citem 

Iz (*Tear Of fs(PATTERN_PALETTE 1) 
-»currentI tem) ( 

/* Unhilte the old item. */ 

HilitePatternI temC&wh ichWindow-> por tRect, 
(*Tear Of fs(PATTERN_PALETTE 1) 

-»currentitem, false); 

/* Hilite the new item. */ 

HilitePatternItemC&whichWindow- por tRect, 
item, true); 


/* Set currentI tem equal to the new item. */ 
(*Tear Of fs(PATTERN_PALETTE ])->currentI tem 
= item; 
) 
break; 


case COLOR_PALETTE: 
item = FindColorItemCmousePt); 


if Citem 
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Iz (*TearOffs COLOR PALETTE) 
-»currentItem) ( 
/* Unhilte the old item. */ 
HiliteColorItemC&whichWindow- portRect, 
(*TearOffs (COLOR. PALETTE ]) 
-»currentItem, false); 
/* Hilite the new item. */ 
HiliteColorItemC&whichWindow- portRect, 
item, true); 


/* Set currentItem equal to the new item. */ 
(*TearOf f s [CCOLOR. PALETTE ) )-› currentItem 
= item; 


) 
) 


%---------------<СК0н EVENT */ 


void GrowEventCwhichWindow) 
WindowPtr whichWindow; 
( 


Rect growRect; 
long size; 
short width; 
short height; 


growRect.left = MIN.WINDOW.WIDTH; 

growRect.top = MIN WINDOW. HEIGHT; 

growRect.right = (*GrayRgn)->rgnBBox.right; 

growRect.bottom = (*GrayRgn)->rgnBBox.bottom 
- TITLE. BAR- HEIGHT; 


size = GrowWindow(whichWindow, Event .where, 
&growRect); 


if(size ! 0) ( 
SetPortCwhichWindow); 


InvalGrowC(whichWindow); 


height = size >> 16; /* HiWord(size). */ 
width = size & OxFFFF; /* LoWord(size). */ 


SizeWindow(whichWindow, width, height, true); 
/* Redraw the scroll bars and grow icon. */ 
) SizeDocumentCwhichWindow); 
) 
к-------------ІМУЛІ GROW 


Invalidate the grow region of the window. This includes 
the area occupied by the scroll bars. */ 


void InvalGrowCwhichWindow) 
WindowPtr whichWindow; 


Rect updateRect; 
updateRect = whichWindow->portRect; 


updateRect.top = updateRect.bottom - SCROLL_BAR_SIZE; 
InvalRect(&updateRect); 


updateRect. top = whichWindow->portRect.top; 

updateRect. left = updateRect.right - SCROLL_BAR_SIZE; 
InvalRect(&updateRect); 
/&*&———————————10$Е EVENT */ 


void CloseEvent(CwhichW indow) 
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is wh ichW indow; 
WindowPeek front; 


ifCEvent.modifiers & optionKey) ( 
ClosingAll = true; 


if CCfront = (WindowPeek) TopWindow) != nil) ( 


if Cfront-»windowKind < Ø) ( 
CloseDeskAccCfront-? windowK ind); 


else ( 


if CCfront—windowK ind == userK ind) 
&& (whichWindow != пі1)) ( 


if(((WindowPeek) whichWindow)- refCon 
== DOCUMENT.WINDOW) ( 
CloseDocument Cwh i chW indow); 


if (TopPalette == TopWindow) ( 
/* Find the new TopDocument. */ 
LocateWindows( О); 


ifCTopDocument != nil) ( 
/* Ensure the TopDocument and its 
controls are hilited properly. */ 
ActivateDocument(TopDocument, 
true); 


) 


else ( 


if CTopDocument != nil) ( 

/* Don’t generate any events that 
might cause the TopDocument to be 
unhilited. */ 

ShowHideCwhichWindow, false); 


else ( 

/* Ensure an activate event is 
generated in case the next visible 
window does not belong to the 

application. */ 

HideW indowCwhichw indow); 


[*————I]EAROFF PALETTE 


version 1.0 
by Don Melton апа Mike Ritter 


Copyright (021987, 1988 by Impulse Technologies, 
Inc., al! rights reserved. 


Filename: Window.c 

Font: Monaco, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2.15 
Project type: APPL 

Creator: TOPD 

Segment: Main */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


#include “Constants.h” 
*include *Variables.h"^ 
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) 
/х---------------ЕХТЕРМА. FUNCTION DECLARATIONS */ else ( 
HiliteWindowCtheDocument, true); 


extern short GoodNewPtr(); /% Еггог.с */ 
extern short GoodResourceC); /* Error.c */ if CTopDocument != nil) ( 
/* Ensure the TopDocument and its controls are 
extern short GetMenuBarHe ight(); /* Interface.c */ unhilited properly. */ 
ActivateDocument(TopDocument, false); 
extern pascal void DrewToolMenu( 2; /* Menu.c */ 
extern pascal void HiliteToolItemC; /* Menu.c */ ) 
extern pascal void DrawPatternMenu(); /% Menu.c */ ShowW indowC theDocument ); 
extern pascal void HilitePatternItem(); /* Menu.c */ 
extern pascal void DrawColorMenu(C); /* Menu.c */ 
extern pascal void HiliteColorItem(); — /* Menu.c */ /5-----------------ОЕТ DOCUMENT RECT */ 
/*x———— Ü 0RWARD FUNCTION DECLARATIONS */ Rect *GetDocumentRect CwindowRect ) 
Rect *windowRect; 
void NewDocument(); ( 
Rect *GetDocumentRect(2; short position; 
short NewScrollBars(?); position = (PositionCounter + DOCUMENT_COUNT ) 
Rect *GetHScrollBarRectC); $ DOCUMENT_COUNT; windowRect-> left 
Rect *GetVScrollBarRect(); = SCREEN_MARGIN 
+ CHORIZONTAL_WINDOW_OFFSET * position); 
void CloseDocument(); windowRect-) top = GetMenuBarHe ight() 
void ActivateDocument( 5; + TITLE_BAR_HEIGHT + SCREEN. MARGIN 
void UpdateDocument( 2; + CVERTICAL_WINDOW_OFFSET * position); 
void SizeDocument(); windowRect-»right = screenBits.bounds.right 
- SCREEN_MARGIN - CCCDOCUMENT_COUNT - 1) 
void MoveSizeScrollBar(); - position) * HORIZONTAL WINDOW. OFFSET); 
windowRect-?bottom = screenBits.bounds.bottom 
void UpdatePalette(); - SCREEN_MARGIN - CCCDOCUMENT COUNT - 1) 
- position) * VERTICAL_WINDOW_OFFSET); 
мм NEW DOCUMENT */ return(windowRect); 
void NewDocument() ( 
StringHendle title; /%------------МЕК SCROLL BARS */ 
WindowPtr theDocument; 
Rect windowRect; short NewScrollBersCwhichWindow) 
WindowPtr whichWindow; 
if (!GoodResource(title = ( 
GetString(DOCUMENT_TITLE_STRING_ID))) ( Rect sBRect; 
return, 
if CGoodNewHandleCNewContro1Cwh ichWindow, 
HLockCtitle); GetHScrollBarRectCwhichWindow, &sBRect), 
NULL, 
if C'GoodNewPtrCtheDocument = NewWindow(nil, VISIBLE, 
GetDocumentRect(&windowRect), 0, 0, 255, 
*title, ѕсго11ВагРгос, 
NOT. VISIBLE, NO_REFCON))) ( 
zoomDocProc, 
BottomPalette, if (GoodNewHand le(NewControlCwhichW indow, 
GO_AWAY_BOX, GetVScrollBerRect(whichWindow, &sBRect), 
DOCUMENT_WINDOW))) ( NULL, 
HUnlock( title); VISIBLE, 
0, 0, 255, 
return; scrollBarProc, 
NO_REFCON))) ( 
if CINewScrollBarsCtheDocument?) ( returnCtrue); 
CloseDocument( theDocument); 
PositionCounter += 1; ) 
HUnlockCtitle2; return(false); 
) 
return; 
/%---------ОЕТ HORIZONTAL SCROLL BAR RECTANGLE */ 
PositionCounter += 1; 
HUnlock( title); Rect *GetHScrollBarRectCwhichWindow, whichRect) 
WindowPtr whichWindow; 
ifCTopPelette != nil) ( Rect *whichRect; 
if(TopPalette != TopWindow) ( twhichRect = whichWindow-?portRect; 
/% Bring the TopPelette to the front end 
generate activate event. */ whichRect-) left -= 1; 
SelectWindowCTopPalette); whichRect-?top = whichRect- bottom 


128 © The Definitive MacTutor, Vol. 4 


- (SCROLL BAR.SIZE - 1); 
whichRect-?right -= (SCROLL_BAR_SIZE - 2); 
whichRect- bottom += 1; 


return(whichRect); 


/*———— — ET VERTICAL SCROLL BAR RECTANGLE */ 


Rect *GetVScrollBarRect(whichWindow, whichRect) 
WindowPtr whichWindow; 
ha *whichRect; 


*whichRect = whichWindow->por tRect; 


whichRect-? left = whichRectright 
- (SCROLL ВАК. 517Е - 1); 
whichRect— top -= 1; 
whichRect- right += 1; 
whichRect->bottom -= (SCROLL ВАК. 517Е - 2); 


return(whichRect); 


) 
/*+—— U L0SE DOCUMENT 


А REAL application would need 8 more complex CloseDocu- 
ment() function. This is just a shell. */ 


void CloseDocument(whichWindow) 
ад whichWindow; 


DisposeWindow(whichWindow); 


PositionCounter -= 1; 


/х----------------АСТІУАТЕ DOCUMENT */ 


void ActivateDocument(whichWindow, activate) 
WindowPtr whichWindow; 
Boolean activate; 


HiliteWindow(whichWindow, activate); 


ifCactivate) ( 
ShowControlCCCH indowPeek ) 
whichWindow2-?controlL ist); 
ShowControlCC*CCW indowPeek ) 
whichWindow)->controlList)-»nextControl); 


else ( 
SetPor tCwhichW indow); 
HideControlCCCW indowPeek ) 
whichWindow)->controlList); 
ValidRect(&(*(CWindowPeek > 
whichWindow)->controlList)->contr Rect); 
HideControlCC*CCHindowPeek ) 
whichWindow)->controlList)-»nextControl); 
Val idRect(&(*C*(CW indowPeek ) 
whichWindow2-?controllist) 
-»nextControl2-?contrlRect?; 


DrawGrowIcon(whichWindow); 


/%-----------------/РГАТЕ DOCUMENT 


А REAL application would need а more complex UpdateDocu- 
mentC) function. This is just a shell. */ 


void UpdateDocument CwhichDocument) 
WindowPtr whichDocument; 
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EraseRect(&whichDocument->portRect); 


/*+——— nF -— TU ZE DOCUMENT */ 


void SizeDocument(whichDocument) 
WindowPtr whichDocument; 


Rect sBRect; 


MoveS izeScrol 1Bar(( CWindowPeek ) 
whichDocument)-?controlL ist, 
GetHScrollBarRect(whichDocument, &sBRect)); 
MoveSizeScrollBarCC*CCH indowPeek) 
whichDocument )-? controll ist) 
-»nextControl, 
GetVScrollBarRect(whichDocument, &sBRect)); 


BeginUpdate(whichDocument ); 
UpdateDocument (wh ichDocument ); 
EndUpdateCwhichDocument); 


ShowControlCCCWindowPeek)whichDocument )->controlList); 
ShowControl(C*(CWindowPeek whichDocument )-» controlList)- 
»nextControl ); 


DrawGrowIconCwhichDocument); 


/*—— — — ——r— Q —0VE AND SIZE SCROLL BAR */ 


void MoveSizeScrollBar(whichScrollBar, sBRect) 
ControlHandle жһісһ5сго11Ваг; 
Rect *sBRect; 


HideControl(whichScrollBar); 


MoveControl(whichScrollBer, sBRect-left, 

SBRect-> top); 

SizeControl(whichScrollBar, sBRect— right - 
sBRect-?left, sBRect— bottom - sBRect- top); 


/х-----------------/РАТЕ PALETTE */ 


void UpdatePaletteCwhichPalette) 
Coo whichPalette; 


/* Use the palette’s refCon to determine which palette 
needs updating. */ 
switch((CWindowPeek) whichPalette)-»refCon) ( 


case TOOL PALETTE : 
DrewToolMenuC&whichPalette-?portRect); 
HiliteToolItemC&whichPalette-?portRect, 
(*Tear Of f sL[TOOL PALETTE 12-? currentItem, 
true); 
break; 


case PATTERN. РА ЕТТЕ: 
DrawPatternMenuC&whichPalette->portRect); 
HilitePatternI temC&whichPalette->portRect, 
(*Tear Offs (PATTERN. PALETTE 1) 
-)»currentItem, true); 
break; 


case COLOR. PALETTE: 
DrawColorMenuC&whichPalette->por tRect); 
HiliteColorItemC&whichPalette-?portRect, 
(*TearOf f SLCOLOR PALETTE ])->currentI tem, 
ігие); 
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Se "ER R OPE: (PALETTE 


version 1.8 
by Don Melton and Mike Ritter 


Copyright (021987, 1988 by Impulse Technologies, 
Inc., ӘП rights reserved. 


Filename: Menu.c 

Font: Courier, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2.15 
Project type: APPL 

Creator: TOPD 

Segment: Main */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


include *Constants.h" 
*include *Variables.h"^ 


/%----------------ЕХТЕКМА FUNCTION DECLARATIONS */ 
/* None */ 

/х%----------------ҒОНМАЕО FUNCTION DECLARATIONS */ 
pascal void DrawToolMenuC ); 


pascal short FindToolItemC); 
pascal void HiliteToolItemC); 


pascal void DrawPatternMenuC ); 
pascal short FindPatternItem(); 
pascal void HilitePatternItem(); 


pascal void DrawColorMenu(); 
pascal short FindColorItemC); 
pascal void HiliteColorItemCO; 


void MovePalette(C); 


/x*x+—— КАМ TOOLS */ 


pascal void DrewToolMenu(CdestRect) 
Rect *destRect; 


DrewPictureCGetPictureCTOOL  РІСТ. 10), destRect); 


/*————————_DRAW PATTERNS %/ 


pascal void DrawPatternMenuCdestRect) 
лай *destRect; 


short index; 
Rect drawRect; 
Pattern thePattern; 


if (MouseInMenu) ( 
EraseRect(destRect); 


forCindex = 1; index < PATTERN.COUNT; 1пдех++) ( 
drawRect = PatternRects[ index]; 
drawRect.top += 1; 
drawRect. left += 1; 
OffsetRect(&drawRect, destRect- left, 
destRect-> top); 


GetIndPattern(&thePattern, PATTERNS_ID, index); 
FillRectC&dresRect, &thePattern); 
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/*—— —  RAW COLORS */ 


pascal void DrawColorMenu(destRect) 
co *destRect; 


CTabPtr colorTable; 
RGBColor saveColor; 
short index; 

Rect drawRect; 


if(MouseInMenu) ( 
EraseRect(destRect); 


HLockCC*C*MaxDev ice2-? gdPMap )-? pmTable); 
colorTable = *(*(*MaxDevice)-? gdPMap)-?pmTable; 
GetForeColor(&saveColor); 
forCindex = 1; index < COLOR_COUNT; index++) ( 
RGBForeColor(&colorTable->ctTablelindex - 1].rgb); 
drawRect = ColorRects[ index]; 
drawRect.top += 1; 
drewRect.left += 1; 
OffsetRectC&drewRect, destRect-? left, 
destRect-? top); 


/* Remember black is а Color QuickDraw pattern. */ 
FillRect(&drawRect, black); 


RGBForeColor(&saveColor); 


| HUnlock((*C*MaxDevice)-)gdPMap)->pmTable); 


/*——— P IND TOOL ITEM */ 


pascal short FindToolItem(mousePt) 
Point mousePt; 


short index; 
forCindex = 1; index < TOOL COUNT; 1пдех++) ( 
if (PtInRectCmousePt, &Тоо1Вес{$ (іпаех))) ( 
return( index); 
return(0); 
) 
/*—— — ——F IND PATTERN ITEM */ 


pascal short FindPatternItemCmousePt) 
Point mousePt; 


short index; 
Rect patternRect; 


forCindex = 1; index < PATTERN COUNT; index**) ( 
patternRect = PatternRects[ index]; 
petternRect.bottom += 1; 
patternRect.right += 1; 
if(PtInRect(mousePt, &patternRect)) ( 
returnCindex); 
return(@); 


) 
J*———— — IND COLOR ITEM */ 
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pascal short FindColorItem(mousePt) 
Point mousePt; 


short index; 
Rect colorRect; 


forCindex = 1; index < COLOR COUNT; index++) ( 


colorRect > ColorRects[index]; 
colorRect.bottom += 1; 
colorRect.right += 1; 


ifCPtInRectCmousePt, &colorRect)) ( 
returnC index); 


return(@); 


) 
[*— — — — —HILITE TOOL ITEM */ 


pascal void HiliteToolItemCdestRect, item, hilite) 
Rect *destRect; 

short item; 

Boolean hilite; 


Rect hiliteRect; 


hiliteRect = ToolRectslitem]; 

hiliteRect.bottom -= 1; 

hiliteRect.right -= 1; 

Of fsetRect(&hiliteRect, destRect-> left, 
destRect-? top); 

Inver tRect(&hiliteRect); 


/%---------ІШІТЕ PATTERN ITEM */ 


pascal void HilitePatternItemCdestRect, item, hilite) 
Rect *destRect; 

short item; 

Boolean hilite; 


Rect hiliteRect; 
PenState savePen; 
Pattern thePattern; 


hiliteRect = PatternRects[item]; 

hiliteRect.top += 1; 

hiliteRect. left += 1; 

Of fsetRect(&hiliteRect, destRect-> left, 
destRect-) top); 


if(hilite) ( 
GetPenStateC&savePen); 


PenSize(2, 2); 
FrameRect(&hiliteRect); 


Реп$12е(1, 1); 
PenMode(patBic); 
InsetRectC&hiliteRect, 2, 2); 
FrameRect(&hiliteRect); 
SetPenState(&savePen); 
else ( 
GetIndPattern(&thePattern, PATTERNS_ID, item); 
FillRectC&hiliteRect, &thePattern); 
) 


[f ИШЕТТЕ, COLOR ITEM: #/ 
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pascal void HiliteColorItemCdestRect, item, hilite) 
Rect *destRect; 

short item; 

Boolean hilite; 


PenState savePen; 
Rect hiliteRect; 
RGBColor saveColor; 
CTabPtr colorTable; 


GetPenState(&savePen); 


hiliteRect = ColorRects[ item]; 

hiliteRect.bottom += 1; 

hiliteRect.right += 1; 

Of fsetRect(&hiliteRect, destRect-> left, 
destRect-? (ор); 


if(hilite) ( 
FrameRect(&hiliteRect); 


PenMode(patBic); 
InsetRect(&hiliteRect, 1, D; 
FrameRect(&hiliteRect); 


) SetPenState(ksavePen); 
else ( 
GetForeColor(&saveColor); 


HLockCC*C*MaxDev i ce2-? gdPMap )-» pmTable); 
colorTable = *(*C*MaxDevice2-»gdPMap2-?pmTable; 


PenMode(patBic); 
FreneRect(&hiliteRect); 


Se tPenState(&savePen); 


RGBForeColor(&colorTable->ctTablefitem - 1].rgb2; 


InsetRect(&hiliteRect, 1, 1); 


/* Remember black is a Color QuickDraw pattern. */ 


FillRect(&hiliteRect, black); 
HUnlock((*(*MaxDevice)-»gdPMap)->pmTable); 
RGBForeColor(&saveColor ); 
) 
/5---------------МОУЕ PALETTE */ 
void MovePaletteCwhichPalette, position) 
WindowPtr whichPalette; 
ба position; 


MoveWindow(whichPalette, position.h, position.v, 
false); 


ifCCTopWindow != nil) && CCOlindowPeek) 
TopWindow)- windowKind != userKind)) ( 


/* The TopWindow is а non-application document. */ 


if (CCWindowPeek) whichPalette)-»visible) ( 

/* The palette is visible. Bring it to the 
front and generate an activate event. */ 

Se lectWindow(whichPalette); 


else ( 

Br ingToFront(whichPalette); 

/* Make the palette visible and generate an 
activate event. */ 

ShowW indow(whichPalette2; 
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else ( 

/* The TopWindow is ап application window or it is 
equal to nil. */ 

BringloFront(whichPalette); 


ifCTopWindow == п11) ( 

/* Мәке the palette visible end generate ап 
activate event. */ 

ShowW indowCwh ichPalette); 


else ( 
/* Маке the palette visible but don't generate 
en activate event. */ 
ShowHideCwhichPalette, true); 
HiliteWindow(whichPalette, true); 


М EA ROFF PALETTE 


version 1.0 
by Don Melton апа Mike Ritter 


Copyright (021987, 1988 by Impulse Technologies, 
Inc., ell rights reserved. 


Filename: Interface.c 

Font: Courier, 9 point 
Teb setting: 2 

Compiler: Lightspeed 2. 15 
Project type: APPL 

Creator: TOPD 

Segment: Main */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


include *Constants.h” 
include "Variables.h^ 


р $———————— FXTERNAL FUNCTION DECLARATIONS */ 


/* None */ 


[FORWARD FUNCTION DECLARATIONS */ 


void Adjust Interf aceC); 
short GetMenuBarHeight(C); 


/*———— R АОЛТ INTERFACE */ 
void Adjustlnterface() ( 


if(Environment.hasColorQD) ( 
MaxDevice = GetMaxDevice(&(*GrauRgn)-,rgnBBox); 


if (C*(*MaxDev ісе )-› дӧРМар)-›ріхе15іге == 8) ( 


ifC!ColorMenuVisible) ( 
/* Insert Color menu if 256 colors. */ 
Inser tMenuCMenus [(COLOR_MENU_INDEX], 0); 
DrawMenuBar (); 
ColorMenuVisible = true; 


else ( 


if (ColorMenuVisible) ( 
/* Remove Color menu if « 256 colors. */ 
DeleteMenuCCOLOR. MENU 10); 
DrawMenuBar (); 
ColorMenuVisible = false; 


if CCCWindowPeek ) 
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Palettes(COLOR_PALETTE])-»visible) ( 
HideW indow(Palettes(COLOR_PALETTE 12; 


PalettesVisible({COLOR_PALETTE) = false; 
) 
) 
) 
/5------------------СЕТ MENU ВАК HEIGHT */ 
short GetMenuBarHeightC) ( 
if (Environment .machineType < envMachUnknown) ( 
/* Arrggh! Someone has the 64K ROMs. */ 
return(28); 


else ( 
return(MBarHe ight ); 


/%---------------ТЕАКОҒҒ PALETTE 


version 1.0 
by Don Melton and Mike Ritter 


Copyright (C)1987, 1988 by Impulse Technologies, 
Inc., 811 rights reserved. 


Filename: Palette.c 

Font: Courier, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2.15 
Project type: APPL 

Creator: TOPD 

Segment: Main */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


include “Constants.h” 
*include “Variables.h” 


/*———— F XTERNAL FUNCTION DECLARATIONS */ 
extern void ActivateDocument(); /* Window.c */ 

extern short GetMenuBarHeight(); — /* Interface.c */ 
/%---------------ҒОККАЕр FUNCTION DECLARATIONS */ 


void LocateWindows(); 
void HiliteUserWindowsC); 
short ActiveWindow(); 


void DoDragW indow( ); 
void DoSelectWindow( ); 
void SendToBack(); 
void Drag(); 


/%----------------10СЛТЕ WINDOWS 


Find the TopWindow whether it belongs to the application 
or not. Also find the TopPalette, the BottomPalette, and the 
TopDocument. These globals will all point to visible windows 
or nil. If the TopDocument is above any visible palette, 
adjust the order of the windows. If а visible non-epplica- 
tion window is between any palettes and the TopDocument, 
adjust the order of the windows. This function replaces 
most uses of FrontWindow() in the application. */ 


void LocateWindows() 


short palettesFound; 
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Boolean inOrder; 
WindowPeek next; 
WindowPeek bottom; 


else ( 
/* Put TopDocument behind BottomPalette. */ 
SendBehindCTopDocument, next); 


/* Initialize globals before search is begun. */ next = (WindowPeek) TopDocument; 

TopWindow = TopPalette = TopDocument = nil; 

/* Make sure all SendBehindC) and NewWindow() calls if CpalettesFound == PALETTE_COUNT) ( 
bring a window to the front if there are no visible palettes. /* If all the palettes are found exit the 
*/ search loop. */ 

BottomPalette = BRING. TO.FRONT; break; 

palettesFound - 0; ) 

inOrder = true; ; ) 

for(next = WindowList; next != nil; if((!in0rder) && (TopPalette != пі1)) ( 


next = next-)nextWindow) ( 


if (TopDocument != nil) ( 


if(next- visible) ( bottom = (WindowPeek) TopDocument; 


if (TopWindow == nil) ( else ( 
/* First visible window. */ bottom = (WindowPeek) BottomPalette; 
TopWindow = (WindowPtr) next; ) 


for(next = (WindowPeek) TopPalette; next != nil; 


if (next->windowKind == userKind) ( next = next-»nextWindow) ( 
if (next->refCon == DOCUMENT_WINDOW) ( if(next != bottom) ( 
if CTopDocument == nil) ( if Cnext->»windowKind != userKind) ( 
/* First visible Document. */ /% Remove the non-application window. */ 
TopDocument = (WindowPtr) next; SendBehind(next, bottom); 
/* Start over. */ 
ifCpalettesFound == PALETTE_COUNT) ( next = (WindowPeek) TopPalette; 
/* If all the palettes are found ) 
exit the search loop. */ 
break; else ( 
) break; 
) ) 
) ) 
else ( i ) 


ifCTopPalette == nil) ( 


/* First visible palette. */ /%-------------НІ1ТЕ USER WINDOWS */ 
TopPalette = (WindowPtr) next; 


void HiliteUserWindowsC) 
/* BottomPalette always points to the ( 
lest visible palette found. */ WindowPeek bottom; 
BottomPalette = (WindowPtr) next; WindowPeek next; 
Boolean hilite; 
short index; 
else ( 


if(TopPelette != nil) ( 
ifCCTopPalette != nil) 


| CTopDocument != nil)) ( if(TopWindow == TopPalette) ( 
/* Shucks, а non-application window is hilite = true; 
visible between the palettes end 
TopDocument. */ else ( 
іп0гдег = false; hilite = false; 
) forCindex = 0; index < PALETTE_COUNT; 1пдех++) ( 
) HiliteWindow(Palettes[index], hilite); 
/* All windows beforelast palette get here */ 
ifCCnext- windowKind == userKind) && Спехі-> refCon if(TopDocument != nil) ( 
|= DOCUMENT_WINDOW)) ( 
palettesFound**; HiliteWindow(TopDocument, hilite); 
/* Unhilite the remaining document windows. */ 
ifCCTopDocument != nil) && Cnext visible?) ( for(next = ((WindowPeek) 
/* А visible palette is beneath the TopDocument)-?nextWindow; next != nil; 
TopDocument. */ next = next-»nextWindow) ( 
if CTopDocument == TopWindow) ( ifCCnext->windowKind == userKind) && 
/* Bring the TopPalette to the front. */ (next-»refCon == DOCUMENT_WINDOW)) ( 
SelectWindow(next); ActivateDocument(next, false); 
TopWindow = (WindowPtr) next; ) 
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) 
) 
) 


/*——— h. r TIVE WINDOW 


Return true if whichWindow is а palette ог the TopDocu- 
ment and the application is active. */ 


short ActiveWindow(whichWindow) 
WindowPtr whichWindow; 


if CwhichWindow != nil) ( 


if((((WindowPeek) TopWindow2-»windowKind 
== userKind) 
&& ((whichWindow == TopDocument) 
|| CCOlindowPeek) whichWindow2-?refCon 
|= DOCUMENT. WINDOW22) ( 
returnCtrue?; 


return(false); 


/х--------------00 DRAG WINDOW 


Since DragWindow() automatically brings а window to the 
front if it’s not already the front window, it must be 
replaced by the application to keep palettes floating above 
documents. */ 


void DoDregWindow(whichWindow) 
WindowPtr whichWindow; 


if (Event modifiers & optionKey) ( 
/*An optional extension of Macintosh interface. */ 
SendToBack (whichW indow); 


else ( 


ifCEvent.modifiers & cmdKey) ( 
Drag(whichWindow); 


else ( 


if C!ActiveWindowCwhichWindow)) ( 
DoSelectWindow(whichWindow); 


else ( 


if CCCCWindowPeek) whichWindow)->refCon 
|= DOCUMENT_WINDOW ) 
&& CwhichWindow != TopPalette)) ( 
Br ingToFrontCwhichWindow); 
/* Force the palette to be updated before 
it is dragged. */ 
SetPor tCwhichW indow); 
UpdatePaletteCwhichWindow); 


DragCwhichW indow); 
) 
) 
) 


/%---------------700 SELECT WINDOW 


Since SelectWindow() brings any window to the front, it 
must be replaced by the application to keep palettes 
floating above documents. */ 


void DoSelectWindow(whichWindow) 
WindowPtr whichWindow; 
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RgnHandle updateRgn; 


if CCOlindowPeek) whichWindow)-»refCon 
== DOCUMENT_WINDOW) ( 


if(TopPalette != nil) ( 
/* Calculate window area not visible that will 
need to be updated. */ 
CopyRgn(whichWindow->visRgn, updateRgn 
= NewRgn()); 
Of f setRgnCupdateRgn, (*((\1пдомРеек) 
wh ichW indow )-> contRgn )->гопВВох . left, 
€*CCWindowPeek Jwhichw indow) 
->contRgn)->rgnBBox. top); 
Dif FRgnCCCWindowPeek) whichWindow2-?strucRgn, 
updateRgn, updateRgn); 


/% Move document below the BottomPalette. */ 
SendBehind(whichWindow, BottomPalette); 
CalcVisBehindCwhichWindow, updateRgn); 
PaintOneCwhichWindow, updateRgn); 


DisposeRgnCupdateRgn); 


if(TopPalette != TopWindow) ( 
/* Bring 811 active application windows 
forward by generating an activate event. */ 
SelectWindowCTopPalette?); 


else ( 
/* Ensure whichWindow and its controls are 
hilited properly. */ 
ActivateDocument(whichWindow, true); 


/* Ensure whichWindow and its controls are 
unhilited properly. */ 
ActivateDocumentCTopDocument, false); 


se ( 
/* № Palettes, bring the document to the front 
end generate an activete event. */ 
SelectWindowC(whichWindow); 


else ( 
if(((WindowPeek) TopWindow2-?windowKind 
== userKind) ( 
/* Bring the palette to the front but don't 
generate ап activate event. */ 
Br ingToFront(whichWindow); 


else ( 

/* Bring the palette to the front апа generate 
an activate event. */ 

SelectWindow(whichWindow2; 


) 
) 


/%----------------СЕЮ TO BACK */ 


void SendToBackCwhichWindow) 
oe whichWindow; 


WindowPeek next; 
WindowPtr below; 


if CCCWindowPeek) whichWindow2-?ref Con 
== DOCUMENT. WINDOW) ( 


below = whichWindow; 


/* Find the document below TopDocument. Documents 
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ere always visible. */ 
Гог(пехі = ((WindowPeek) whichWindow2-?nextWindow; 
next !z nil; next = next nextWindow) ( 


if CCnext->windowKind == userKind) && 
Cnext-»refCon == DOCUMENT_WINDOW)) ( 
below = (WindowPtr) next; 
break; 


) 

ifCwhichWindow != below) ( 
/* Send document all the way to the back. */ 
SendBeh indCwhichWindow, nil); 


if(TopPalette == TopWindow) ( 
/* Ensure whichWindow and its controls are 
unhilited properly. */ 
ActiveteDocument(whichWindow, false); 


/* Find the new TopDocument. */ 

LocateWindowsC); 

/* Ensure the TopDocument and its controls 
ere hilited properly. */ 

ActivateDocumentCTopDocument, true); 


) 


else ( 


if((whichWindow != BottomPalette) && CTopPalette 
Iz BottomPalette)) ( 
/* Move palette behind the BottomPalette. */ 
SendBehindCwhichWindow, BottomPalette); 


) 
) 


J i— RA */ 


void Drag(whichWindow) 
WindowPtr whichWindow; 
( 


GrafPtr sevePort; 
Rect dregLimit; 
RgnHandle dragRgn; 
long result; 

Point move; 

Rect *portBounds; 


if (WaitMouseUp()) ( 
GetPort(&savePort); 
SetPor tCWMgrPor t); 


SetClip(CGrayRgn); 

/* Ensure the drag outline does not get drawn 
through the windows above whichWindow. */ 

ClipAboveCwhichWindow); 


dragLimit = screenBits.bounds; 
dregLimit.top = GetMenuBarHeight(); 


CopyRgnCCCWindowPeek) whichWindow2-?strucRgn, 
dragRgn = NewRgn()); 


/* Drag outline of window around the screen. */ 
result = DragGrayRgn(dragRgn, Event.where, 
&dregLimit, &dragLimit, noConstraint, nil); 


move.v = result >> 16; /* HiWord(result). */ 
move.h = result & OxFFFF; /* LoWord(result). */ 


ifCmove.v != 0х8000) ( 
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/* The mouse button has been released inside 
dragLimit. See ‘Inside Macintosh Volume I, ’ 
pages 294-295, for expalnation of 0х8000. */ 
if CCCCGrafPtr) whichWindow)-)portVersion 
& 0хс000) ( 
/* The window is a color port. */ 
portBounds = &C*CCCGrafPtr) 
whichWindow2-?portP ixMap2-? bounds; 


else ( 
/* The window is ап old-style port. */ 
portBounds = &whichWindow-?portBits bounds; 


move.v += whichWindow- portRect.top 

- portBounds-? top; 
move.h += whichWindow— portRect. left 

- portBounds-? left; 
MoveWindow(whichWindow, move.h, move.v, false); 


) 
DisposeRgnCdragRgn); 
SetPortCsavePort); 


TEAR OEP (PALETTE 


version 1.0 
by Don Melton and Mike Ritter 


Copyright (C)1987, 1988 by Impulse Technologies, 
Inc., 811 rights reserved. 


Filename: Dialog.c 

Font: Courier, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2.15 
Project type: APPL 

Creator: TOPD 

Segment : Main */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


include *Constants .h^ 
* include “Variables .h” 


/*——  — — ———EXTERNAL FUNCTION DECLARATIONS */ 


extern short GoodResource(); /* Error.c */ 
extern short GetMenuBarHeight(); /* Interface.c */ 


/<——— — —————FORWARD FUNCTION DECLARATIONS */ 
void DoAbout(); 


short PositionDialog(); 
pascal Boolean DialogFilter(); 


/*—__—___—___—____—00 ABOUT */ 


void DoAbout() ( 
DielogRecord theDialogRecord; 
short itemHit; 


if (PositionDialogCABOUT_DIALOG_ID)) ( 
(void) GetNewDialogCABOUT_DIALOG_ID, 
&theDialogRecord, BRING_TO_FRONT); 
ShowW indow(& theD ia logRecord); 


do { 
ModalDialog(DialogFilter, &itemHit); 


whileCitemHit == 0); 


CloseDialog(&theDialogRecord); 
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) 


/%----------------РОВІТІОМ DIALOG 


PositionDialog() centers а DITL resource horizontally 


end positions it one-third down 
the screen vertically. */ 


short PositionDialog(whichID) 
rid whichID; 


Point where; 
DielogTHnd! theTemplate; 


ifC!GoodResourceCtheTemplete = (DialogTHndl) 
GetResourceC^DLOG^, whichID))) ( 
return(false); 


) 
OffsetRectC&C*theTemplate)-»boundsRect, 

- (*theTemplete2-?boundsRect . left 

+ (CscreenBits.bounds .right 

- screenBits.bounds. left) 

- (C*theTenplete)2-?boundsRect .r ight 

- (¥theTemplate)-»boundsRect.left)) / 2, 
(*theTemp late)->boundsRect . top 
C(CCscreenBi ts .bounds .bottom 
screenBi ts bounds . top-GetMenuBarHe ight C2) 
CC*theTemplate2-?boundsRect .bot tom 
(*theTemplate)->boundsRect.top)) / 3) 

+ GetMenuBarHeight()); 
return(true); 


Ú l| j + 1 


/%-----------------ОІЛОСҒИТЕК 


DialogFilterC) allows exit of М№ода101а109() on any 
mouseDown or keyDown event. */ 


pascal Boolean DialogFilterCwhichDialog, whichEvent, 
whichItem) 

DialogPtr whichDialog; 

EventRecord *whichEvent; 

short *whichItem; 


WindowPtr whichWindow; 


if (CwhichEvent-> what == mouseDown) || 
CwhichEvent->what == keyDown)) ( 


if CCFindWindowCwhichEvent->where, &whichWindow) 
zs inMenuBer) 
|| CCwhichEvent->what == keyDown) && 
(whichEvent-?modifiers & cmdKey))) ( 
/* Re-post event end ignore апу error. */ 
(void) PostEvent(CwhichEvent-> what, 
whichEvent-?message); 


) 
*whichItem = 1; 
return(Ctrue); 


ве ( 
return(false); 


%----------ТЕАЕЮОЕҒЕҒ PALETTE 


version 1.0 
bu Don Melton and Mike Ritter 


Copyright (C)1987, 1988 by Impulse Technologies, 
Inc., ӘТІ rights reserved. 
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Filename: Error.c 

Font: Courier, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2. 15 
Project type: APPL 

Creator: TOPD 

Segment: Main */ 


/*GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


Sinclude *Constants.h"^ 
include *Variables.h^ 


/%-------------ЕХТЕНМАІ. FUNCTION DECLARATIONS */ 

/* None */ 

/%----------------ҒОВМАНЕО FUNCTION DECLARATIONS */ 
short GoodNewPtr(); 

short GoodNewHandleC); 

short GoodResource(); 

pascal long RecoverMemory(); 
/%--------------------60000 NEW POINTER */ 


short GoodNewPtrCwhichP tr) 
Ptr whichPtr; 
( 


ifCCwhichPtr != nil) && (МетЕгг == noErr)) ( 
return( true); 


return(false); 


/*——__—_—_——————————600D NEW HANDLE */ 


short GoodNewHandleCwhichHandle) 
Handle whichHandle; 


ifCwhichHandle != nil) ( 
return(GoodNewP trC*wh ichHandle )); 


return(false); 


/%----------------0000 RESOURCE */ 


short GoodResource(Cwh i chHandle) 
Handle whichHandle; 


if(CwhichHandle != nil) && (ВезЕггог() == noErr)) { 
ifC*whichHandle != nil) ( 


return( true); 


return(false); 


/*———_——————————RECOVER MEMORY 


RecoverMemory() is а very simple grow zone function 
designed to prevent the ROM or resident software such as 
desk accessories from generating out of memory errors. After 
this function is called, the application will quit before 
processing the next event. 


See ‘Inside Macintosh Volume II,’ pages 42-43, about 
setting up grow zone functions. */ 
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pascal long RecoverMemory(memoryNeeded ) 
Size memoryNeeded; 


long buf ferSize; 
SetUpA5(); 
bufferSize = GetHandleSizeCMemoryBuf fer); 


if(CbufferSize != Ø) ( 
DisposHand1e(MemoryBuf f er ); 


OutOfMemory = true; 
RestoreA5C); 


returnCbufferSize); 


{к —————————ЕАЕОРЕ PALETTE 


version 1.0 
by Don Melton and Mike Ritter 


Copyright (621987, 1988 by Impulse Technologies, 
Inc., all rights reserved. 


Filename: Initialize.c 

Font: Courier, 9 point 
Tab setting: 2 

Compiler: LightspeedC 2. 15 
Project type: APPL 

Creator: TOPD 

Segment : Initialize 


IMPORTANT! Use ResEdit to set the code resource of this 
segment to unlocked. */ 


/*-GLOBAL CONSTANT DEFINITIONS AND VARIABLE DECLARATIONS */ 


®include “Constants .h” 
#include “Variables.h’ 


/*————_———————EXTERNAL FUNCTION DECLARATIONS */ 


extern short GoodNewPtr(); /* Еггог.с */ 

extern short GoodNewHandle(); /* Error.c */ 
extern short GoodResource(); /* Error.c */ 
extern pascal long RecoverMemory(); /* Error.c */ 
extern pascal void DrawToolMenuC); /* Menu.c */ 
extern pascal short FindToolItemC); /* Menu.c */ 


extern pascal void HiliteToolItemC);/* Menu.c */ 

extern pascal void DrawPatternMenuC); /% Menu.c */ 
extern pascal short FindPetternItem(); — /* Menu.c */ 
extern pascal void HilitePatternItem(); /* Menu.c */ 
extern pascal void DrawColorMenu(); /* Menu.c */ 
extern pascal short FindColorItem();/* Menu.c */ 

extern pascal void HiliteColorItem(); /Х Menu.c */ 


/*————————————————F ORWARD FUNCTION DECLARATIONS */ 
void Initialize); 


void SetupEnvironment(); 
void SetupMemory(C); 


void SetupPalettes(); 

void SetupToolPalette(); 
void SetupPatternPalette(C); 
void SetupColorPalette(); 
void SetupPaletteRects(); 


void SetupMenusC); 
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/%-----------------ІНІТІЛІГЕ */ 
void Initialize() ( 


InitGrafC&thePort); 
InitFonts(); 

Ini tWindows( ); 

Ini tMenus(); 
TEInit(); 
InitDialogs(nil); 
InitCursor(); 


FlushEventsCeveryEvent, 0); 


SetupEnvironmentC); 
SetupMemory(); 
SetupPalettes(); 
SetupMenusC ); 


TopWindow = TopPalette = TopDocument = nil; 
BottomPalette = BRING_TO_FRONT; 


PositionCounter = 0; 
Sleep = SLEEP_DURATION; 


ClosingAll = Quitting = Finished = false; 


/%-----------------<ЕТИУР ENVIRONMENT */ 
void SetupEnvironment() ( 


if CSysEnvironsCVERSION.REQUESTED, & Environment) 
== envBadSel) ( 
ExitToShe11C); 


ifCEnvironment.machineType >= envMachUnknown) ( 
WNEIsImplemented = 
NGetTrapAddress 
CWAIT.NEXT. EVENT. TRAP NUMBER, Tool Trap) 
!= NGetTrapAddress 
CUNIMPLEMENTED_TRAP_NUMBER, ToolTrap); 
else ( 
WNEIsImplemented = false; 


) 
/%---------------:5ЕТІР MEMORY */ 
void SetupMemory() ( 

MaxApplZone(C); 


MoreMasters(); 
MoreMasterst); 


ifC!GoodNewHandleCMemorgBuf fer = 
NewHandleCMEMORY.BUFFER.SIZE22) ( 
ExitToShe11C); 


OutOfMemory = false; 


/* Setup а simple grow zone function. */ 
SetGrowZone(RecoverMemory); 


) 
/*—— v T re —  o- -.SETUP PALETTES */ 
void SetupPalettes() ( 


short index; 
TearOffMGlobalsPtr whichTearOff; 
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Rect windowRects (РА ЕТТЕ. С00МТІ; 
short attributes; 


forCindex = Ø; index < PALETTE-COUNT; index**) ( 


/* Get а handle to TearOffMenuGlobals. */ 
if C! GoodResourceCTearOf f s[ index] 
= (TearOffMGlobalsHdl) 
GetResourceCTEAR. OFF -MENU-CLOBALS. ТҮРЕ, 
TOOL. MENU.ID + index))) ( 
ExitToShel1(); 


MoveHHi (Tear 0f fsf index) ); 
HLock(TearOffslindex]); 
whichTearOff = *TearOffslindex]; 


switchCindex) ( 


case TOOL_PALETTE: 
SetupToolPaletteCwhichTearOff , 
&windowRects[index12; 
break; 


case PATTERN. PALETTE : 
SetupPetternPaletteCwhichTearOf Г, 
&windowRects[index1); 
break; 


case COLOR. PALETTE: 
SetupColorPaletteCwhichTearOf f, 
&windowRects[ index12; 


) 
if (Environment .hasColorQD) ( 
/* Create a color port. */ 
if C!GoodNewPtr (Palettes [index ] 
= NewCWindow(nil, 
&windowRectsl index], 
NULL, 
NOT. VISIBLE, 
/* Set procedure ID based on 
PaletteWDEF resource ID. */ 
(16 * PALETTE WOEF 10) 
* noGrowDocProc, 
BRING.TO.FRONT, 
00. AWAY. BOX, 
(long) index)» ( 
ExitToShel1(); 


else { 
/* Create an old-style port. */ 
if C!GoodNewPtr (Palettes[ index ] 
= NewWindow(nil, 
&windowRects[ index], 
NULL, 
МОТ. VISIBLE, 
/* Set procedure ID based on 
PaletteWDEF resource ID. */ 
(16 * PALETTE WOEF 10) 
* noGrowDocProc, 
BRING_TO_FRONT, 
GO_AWAY BOX, 
(long) index))) ( 
ExitToShe11C); 


/* Finish Initializing TeaerOf fMenuGlobals 
structure. */ 
whichTearOf f > environment 


= &Environment; 
whichTearOf f-»paletteWindow = 


Palettesl index]; 
HUnlock(TearOf fs index 10; 
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[$————————— —-SETUP TOOL PALETTE */ 


void SetupToolPaletteCwhichTear0ff, windowRect) 
TearOffMGlobalsPtr whichTearOff ; 
Rect *windowRect; 


PicHendle toolPicture; 


ifC!GoodResourceCtoolPicture = 
GetPictureC(TOOL_PICT_ID))) ( 
ExitToShe11C); 


) 
HNoPurge( too ]Picture); 


/* Calculate palette’s portRect from toolPicture. */ 
*windowRect = (*toolPicture)-»picFrame; 
OffsetRectCwindowRect, -windowRect-? left, 
-windowRect-? top); 


SetupPaletteRectsC&ToolRects, 
TOOLS. ACROSS, 
TOOLS. DOWN, 
(windowRect-?right + 1) / TOOLS. ACROSS, 
(windowRect-?bottom + 1) / TOOLS_DOWN); 


/* Initialize the TearOffMenuGlobals structure. */ 
whichTearOff-»currentItem = DEFAULT. TOOL; 
whichTearOf f-»drawMenuProc = DrawToolMenu; 
whichTearOff-»findItemProc - FindToolItem; 
whichTearOff-»hiliteItemProc = HiliteToolItem; 


/*#—— s L SETUP PATTERN PALETTE */ 


void SetupPatternPalette(whichTearOff, windowRect) 
TeerOffMGlobalsPtr whichTeerOff; 
Rect *windowRect; 


/* Calculete the portRect from number of patterns. */ 
windowRect-? left = 0; 
windowRect-) top = 0; 
windowRect-?right = CPATTERNS_ACROSS 
х (PATTERN_ITEM_WIDTH + 1)) + 1; 
windowRect->»bottom = CPATTERNS. DOWN 
ж (PATTERN_ITEM_HEIGHT + 1)) + 1; 


SetupPaletteRects(&PatternRects, 
PATTERNS_ACROSS, 
PATTERNS_DOWN, 
PATTERN_ITEM_WIDTH + 1, 
PATTERN_ITEM_HEIGHT + 1); 


/* Initialize the TearOffMenuGlobals structure. */ 
whichTearOf f-»currentItem = DEFAULT. PATTERN; 
whichTearOf f-»drewMenuProc = DrewPetternMenu; 
whichTearOf f-»f indItemProc = FindPatternI tem; 
whichTearOff-»hiliteItemProc = HilitePatternI tem; 


ЕР COLOR PALETTE */ 


void SetupColorPalette(whichTearOff, windowRect) 
TearOffMGlobalsPtr whichTearOff ; 
Rect *windowRect; 


/* Calculate the portRect from the number of colors. */ 
windowRect-? left = 0; 
windowRect-?top = 0; 
windowRect-^?right = CCOLORS. ACROSS 
х (COLOR ITEM-.WIDTH + 1)) + 1; 
windowRect-»bottom = CCOLORS_DOWN 
ж (COLOR_ITEM_HEIGHT + 1)) + 1; 
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) 


SetupPaletteRects(&ColorRects, 
COLORS_ACROSS, 
COLORS_DOWN, 
COLOR_ITEM_WIDTH + 1, 
COLOR_ITEM_HEIGHT + 1); 


/* Initialize the TearOffMenuGlobals structure. */ 
whichTearOf f-»currentIiem = DEFAULT_COLOR; 
whichTear0f f->drawMenuProc = DrawColorMenu; 
whichTearOff-»findItemProc = FindColorItem; 
whichTearOff-»hiliteItemProc = HiliteColorItem; 


EIU PALETTE .RECTS *7 


void SetupPaletteRects(whichRects, itemsAcross, 
itemsDown, itemWidth, itemHeight) 

Rect *whichRects; 

short itemsAcross; 

short itemsDown; 

short itemWidth; 

(de itemHeight; 


) 


short index; 
short across; 
short down; 


whichRects-?left = 0; 
whichRects-> top = 0; 
whichRects—right = 0; 

whichRects->bottom = Ø; 


index = 1; 
forCdown = Ø; down < itemsDown; down**) ( 


forCacross = 0; 
across < itemsAcross; acrosst+) ( 

CwhichRects + index)-) left 

= across * itemWidth; 
CwhichRects + index)-) (ор 

= down * itemHeight; 
CwhichRects + index)-»right 

= Cacross + 1) * itemWidth; 
CwhichRects + index)->bottom 

= (down + 1) * itemHeight; 
index += 1; 


/Х%----------------5ЕТУР MENUS */ 


void SetupMenus() ( 


short index; 


forCindex = APPLE_MENU_INDEX; 
index < MENU_COUNT - 1; index++) ( 
Menus[index] = GetMenuC index + MENU_ID_OFFSET); 
InsertMenuCMenus[ index], 0); 


) 
AddResMenuCMenus [APPLE MENU. INDEX], ‘DRVR’); 
ColorMenuVisible = false; 


if (Environment .hasColorQD) ( 
MaxDevice = GetMaxDevice(&(*GrayRgn)->rgnBBox); 


Menus [COLOR_MENU_INDEX] = 
Ge tMenuCCOLOR_MENU_ID); 


if (C*(*MaxDev ice )->gdPMap )-»pixelSize == 8) ( 
/* Insert Color menu if 256 colors. */ 
Inser tMenuCMenus [COLOR MENU..INDEX1, 0); 
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ColorMenuVisible = true; 


) 
DrewMenuBar(); 


/*PALETTE WINDOW DEFINITION 


version 1.0 
by Don Melton and Mike Ritter 


Copyright (621987, 1988 by Impulse Technologies, Inc., 811 
rights reserved. 


Filename: PeletteWOEF .c 
Font: Monaco, 9 point 
Teb setting: 2 

Compiler: LightspeedC 2. 15, 


Project type: WDEF, ID: 128, Name: (None) 


IMPORTANT! Use ResEdit to set the WDEF resource to non- 
purgeable. 


DESCRIPTION 


PaletteWDEF is а WDEF code resource designed to display 
windows that mimic the appearance of tear-off palettes in 
HyperCard. However, PaletteWDEF will unhilite a title bar, and 
PaletteWDEF windows have a 3 pixel indented drop shadow just like 
а menu. 


To use PaletteWDEF, an application must calculate the 
procedure ID of the window to be created, at runtime or store it 
іп а WIND or DLOG resource. With PaletteWDEF’s resource ID being 
128, the folllowing code #111 create а new palette window: 


w = NewWindow(p, bounds, title, visible, (16 * 128) + 
noGrowDocProc, behind, goAwayFlag, refCon); 


See ‘Inside Macintosh Volume I,’ page 298, for more 
information on calculating the procedure ID. 


Note: Although NewCWindow() ог GetNewCWindow() can be used 
with PaletteWDEF, it does not support the use of wctb resources 
for color information, or respond visibly to SetWinColor(). 


Note: PaletteWDEF will not draw а grow region or zoom box 
іп а window. It completely ignores any and 811 variation codes 
passed to it. */ 


/x—— — n 1 -  —-.YNCLUDE DEFINITIONS */ 


*include “MacTypes.h” 
include *"MemoryMgr .h^ 
include "Quickdraw.h^ 
* include "WindowMgr .h^ 


/*—————————————CLOBAL CONSTANT DEFINITIONS */ 


typedef struct QuickDraw ( 
char private[76]; 
long rendSeed; 
BitMep screenBits; 
Cursor arrow; 
Pattern dkGray; 
Pattern 1t6ray; 
Pattern gray; 
Pattern black; 
Pattern white; 
GrafPtr thePort; 

) QuickDraw; 


"def ine PALETTE_TITLE_BAR_HEIGHT 10 
"def ine PALETTE_SHADOW_INDENT 3 
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/5-------------------СІОВА VARIABLE DECLARATIONS */ 


/* None, even though the LightspeedC compiler allows it, others 
don't. */ 


/Jx——— ——-EXTERNAL FUNCTION DECLARATIONS */ 


/* None, theu re not allowed. */ 
/%5----------------------ҒОВРМАКО FUNCTION DECLARATIONS */ 


pascal long main(); 

void DrawWindow(); 

long TestWindowHit(); 
void CalcWindowRegionsC); 


/5--------------РАЕТТЕ WINDOW DEFINITION 


The main function is called by the Window Manager in the 
Macintosh ROM. It’s designed to repsond to three messages: drawing 
the window, testing which part of the window has been hit, and 
calculating the various window regions. 


See ‘Inside Macintosh Volume I,’ pages 297-382, for more 
information on this function. */ 


pascal long mainCvariation, whichWindow, message, parameter) 
short variation; 

WindowPtr whichWindow; 

short message; 

ce parameter ; 


long result; 
result = 9; 


/* Use multiple “if? rather than ‘switch’ to avoid linking 
of 400% bytes of runtime code. */ 


if(message == wDraw) ( 
DrewWindow(whichWindow, parameter); 


else if (message == wHit) ( 
result = TestWindowHitCwhichWindow, parameter); 


else if(message == wCalcRgns) ( 
CalcWindowRegions(whichW indow); 


return(result); 


) 
/*—— . r. DURAW WINDOW */ 


void DrawWindow(whichWindow, parameter) 
WindowPtr whichWindow; 
ai parameter ; 


Rect frame; 

Rect goAway; 

PenState savePen; 
short tone; 

short index; 

Pattern hilite; 
QuickDraw *qdGlobals; 


/* Set up a pointer to QuickDraw’s global variables. */ 
606100818 = (QuickDraw *)(*(Byte **)CurrentAS 
- (sizeof(QuickDrew) - sizeof (GrafPtr))); 


if (CCWindowPeek) whichWindow)-— visible) ( 
/* Calculate the window frame. */ 
frame =  (*(QindowPeek) whichWindow)->strucRgn)- 
?rgnBBox; 
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freme.bottom -= 1; 
freme.right -= 1; 


/* Calculate the goAway box. */ 
goAway = frame; 

goAway. (ор += 2; 

goAway. left += 8; 

goAway.bottom = goAway.top + 7; 
goAway.right = goAway.left + 7; 


if (parameter != 0) { 
/* Hilite the goAway box. */ 
Inver tRect (&goAway ); 


else ( 
/* Draw the window frame, drop shadow, title bar and 


>e 
— 


goAway box. 
GetPenState(&savePen); 
PenNormal(); 


/* Draw the frame. */ 
FrameRect(&frame); 


/* Draw the drop shadow. */ 

Movelo(frame.left + $PALETTE_SHADOW_INDENT, 
frame .bottom); 

LineToCframe right, frame.bottom); 

LineToCframe.right, frame.top + 
PALETTE_SHADOW_INDENT ); 


/* Calculate and draw the title bar. */ 

frame bottom = frame. top + CPALETTE_TITLE_BAR_HEIGHT + 1); 
FrameRect(&frame); 
InsetRect(&frame, 1, 1); 


if CCCWindowPeek) whichWindow)-»hilited) ( 
/* Adjust pattern and fill title bar. */ 
tone = freme.left & 1? 0x55 : бхаа; 


forCindex = 0; index <= 7; index++) ( 
hilitelindex] = Cindex + frame.top) & 1 ? tone : Ø; 


FillRect(&frame, &hilite); 


/* Draw the goAway box. */ 
frame = goAway; 
InsetRect(&frame, -1, -1); 
EraseRect(&frame); 
FrameRect(&goAway ); 


else ( 
FillRect(&frame, qdGlobals- white); 


setPenState(&savePen); 


) 
/*——— Y  IEST WINDOW HIT */ 


long TestWindowHitCwhichWindow, parameter) 
WindowPtr whichWindow; 
long parameter; 


Point where; 
Rect drag; 
Rect goAway; 


where.v = parameter >> 16; /* HiWord(paremeter). */ 
where.h = parameter & OxFFFF; /* LoWord(parameter). */ 
ifCPtInRectCwhere, — &C*CCOlindowPeek) whichWindow)- 
»contRgn )-»rgnBBox)) { 


return(wInContent); 
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else ( 
/* The mouse is in the window frame. */ 
drag = (*((WindowPeek) — whichWindow2- strucRgn)- 
yrgnBBox; 


drag.bottom = drag.top + (PALETTE_TITLE_BAR_HEIGHT + 1); 
drag.right -= 1; 


if(PtInRect(where, &drag)) ( 
goAway = drag; 
goAway.top += 2; 
goAway. left += 8; 
goAway.bottom = goAway.top + 7; 
goAway.right = goAway.left + 7; 


ifCCCCWindowPeek) whichWindow)-»hilited) — && 


(PtInRect(where, &goAway))) ( 


/* 


return(wInGoAway); 


return(wInDrag); 


) 
returnCwNoHit); 


CALCULATE WINDOW REGIONS */ 


void CalcWindowRegionsCwhichWindow) 
WindowPtr whichWindow; 
( 


Rect windowRect; 
RgnHandle shadowRgn; 


/* Calculate the content region of the window. */ 
windowRect = whichWindow-?portRect ; 


OffsetRectC&windowRect, = whichWindow- 


»por tBits.bounds. left, - whichWindow portBits.bounds. top); 


RectRgn((CWindowPeek) whichWindow)->contRgn, &window- 


Rect); 


/* Calculate the structure region of the window. */ 
/* First, calculate the window frame. */ 
windowRect.top -= PALETTE TITLE BAR HEIGHT + 1; 
windowRect.left -= 1; 

windowRect.bottom += 1; 

windowRect.right += 1; 


RectRgnCCCWindowPeek) whichWindow)-»strucRgn, &window- 


Rect); 


/* Next, calculate the frame’s drop shadow. */ 
windowRect.top += PALETTE_SHADOW_INDENT; 
windowRect. left += PALETTE_SHADOW_INDENT; 
windowRect .bottom += 1; 

windowRect.right += 1; 

RectRgnCshadowRgn = NewRgn(), &windowRect); 


/* Combine the frame and the shadow to calculate the 


structure. */ 


UnionRgnCCCWindowPeek) whichWindow2-»?strucRgn, shadowRgn, 


CCWindowPeek) whichWindow)->strucRgn); 


/* 


DisposeRgn(shadowRgn ); 


TEAROFF MENU DEFINITION 


version 1.0 
by Don Melton and Mike Ritter 


Copyright (C)1987, 1988 by Impulse Technologies, 
Inc., 811 rights reserved. 
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Filename: Tear Of f MDEF .c 


Font: Monaco, 9 point 
Tab setting: 2 

Compiler: LightspeedC 2.15 
Project type: MDEF 

ID: 128 

Name: (None) 


IMPORTANT! Use ResEdit to set the MDEF resource to non- 
purgeable. 


IMPORTANT! Use ResEdit or FEdit to change hex string 
^21c809ce^ at hex offset 14 in the MDEF resource to 
‘4e714e71.’ This substitutes two ‘nop’ instructions for a 
'move.] aQ,ToolScratch. ’ 


DESCRIPTION 


TearOffMDEF is ап MDEF code resource implementing the 
common actions of tear-off menus for any application. It’s 
designed to communicate with an application via a TearOff- 
MenuGlobals structure іп а TOMG resource. At runtime, Tea- 
rOffMDEF uses the menuID of the MenuInfo, passed to it by the 
Macintosh ROM, to find a TOMG resource of the same ID. The 
Tear0ffMenuGlobals structure contains eight elements: 


drawMenuProc A function pointer to a menu in global 
coordinates within the WMgrPort. 


f indI temProc A function pointer to a pascal-type 
procedure which returns the number of the menu item where the 
mouse is currently located. 


hiliteItemProc A function pointer to a pascal-type 
procedure which hilites or unhilites a given menu item. 


environment A pointer to a SysEnvRec used to test 
if the 64K ROMs ere present. 


paletteWindow A WindowPtr used to calculate 
menuWidth, menuHeight, and the structure boundary from the 
window's portRect. 


currentItem А short int containing the number of 
the currently hilited menu item. 


position A Point passed to the application from 
TeerOffMDEF indicating the top, left point, іп global coordi- 
nates, of a torn-off menu. 


itemHilited À Boolean used internally by Tea- 
rOffMDEF . 

All of these elements, except position апа itemHilited, 
must be initialized by the application before а tear-off menu 
is inserted into the menu list. 


IMPORTANT! The menuProc field of а tear-off MENU resource 
must equal TearOffMOEF's resource ID. 


The application is completely responsible for the appeer- 
ence of the menu. TearOffMDEF does not contain code to draw 
the contents of & menu, nor does it contain code to hilite 
menu items. А set of the three following procedures must be 
declared in the application for each tear-off menu: 


pascal void DrawMenuProc(destRect) 
Rect *destRect; /* The menu rectangle in the 
current grafPort. */ 


pascal short FindI temProc(mousePt ) 
Point mousePt; /*The point in which the mouse 
is currently located, relative 
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to the top, left of the menu 
rectangle. 


The number of the menu item 
where the mouse is currently 
located should bereturned to 
TearOffMDEF by the application. 
%/ 


pascal void HiliteItemProcCdestRect, item, hilite) 
Rect *destRect; /* The menu rectangle in the 
current grefPort. */ 

/* The number of the menu item 
to be hilited or unhilited. 
Boolean hilite; /* A flag indicating the hilite 

state. Set true to hilite and 
false to unhilite. 


short item; 


IMPORTANT! The segment in which these procedures ere 
declared must remain locked at runtime. 


It’s very simple for the application to call these same 
procedures to draw into the window once the user has torn it 
off 


TearOffMDEF will return -1 to the Menu Manager if a menu 
has been torn off. It’s the application’s responsibility to 
move the window into position and make it visible. 


Note: TearOffMDEF is not designed to implement pop-up 
menus. */ 


/3— INCLUDE DEFINITIONS */ 


* include *MacTypes .h^ 

* include “MemoryMgr .h^ 
*include “MenuMgr .h^ 
*íinclude *OSUtil.h^ 
"include *pescal.h^ 
*íinclude *Quickdraw.h^ 
include “ResourceMgr .h^ 
include “WindowMgr .h” 


/5------------------С10ВА CONSTANT DEFINITIONS */ 


define nil Ø 


typedef struct QuickDrawGlobals { 
char private(76]; 
long randSeed; 
BitMap screenBits; 
Cursor arrow; 
Pattern dkGray; 
Pattern 1tGray; 
Pattern gray; 
Pattern black; 
Pattern white; 
GrafPtr thePort; 

} QuickDrewGlobals; 


typedef struct TearOffMenuGlobels ( 
void (*drawMenuProc)(); 
short (*findItemProc)(); 
void (*hiliteltemProc)(); 
SysEnvRec *environment; 
WindowPtr peletteWindow; 
Point position; 
short currentItem; 
Boolean itemHilited; 
} TearOffMenuGlobals, *TeerOffMGlobalsPtr, **TearOffMGlobal- 
sHdl; 


"def ine TEAR_OFF_MENU_GLOBALS_TYPE ‘TOMG’ 
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8def ine TEAR_OFF_MARGIN 15 
8def ine MOVE РА ЕТТЕ. ІТЕМ (-1) 


8def ine PALETTE ТІТІЕ ВАК. НЕІОНТ 10 
Sdef ine PALETTE_SHADOW_INDENT 3 
"def ine PALETTE_OFFSET 5 


Һ-----------С0вА VARIABLE DECLARATIONS */ 


/* None, even though the LightspeedC compiler allows it, 
others don’t. */ 


/5------------------ЕХТЕРКМАІ FUNCTION DECLARATIONS */ 
/* None, they’re not allowed. */ 
A FORWARD FUNCTION DECLARATIONS */ 


pascal void main(); 
void Chooseltem(); 
void DregMenuC); 


%----------------ТЕАКОЕР MENU DEFINITION 


The main function is called by the Menu Menager in the 
Macintosh ROM. It’s designed to repsond to three messages: 
drewing the menu, choosing ап item, and calculating the menu 
size. It will not respond to а pop-up menu request. Before it 
dispatches to these routines, it first checks to see if the 
TeerOffMenuGlobals structure is available on the heap, and 
locks it down. It does nothing if it cannot find this struc- 
ture. 


See 'Inside Macintosh Volume I,^ pages 362-363, for more 
information on this function. */ 


pascal void main(message, whichMenu, menuRect, hitPt, 
whichI tem) 

short message; 

MenuHandle whichMenu; 

Rect *menuRect; 

Point hitPt; 

cc *whichI tem; 


TeerOf fMGlobalsHd! whichTOMGlobalsHdl; 
TearOffMGlobalsPtr tearOffMGlobals; 


/* Make sure А5 is valid so the application code can 
use it’s own global variables. */ 
SetUpA5(); 


/* Use the menuID to get а handle to the correct TearOff- 
MenuGlobals structure. */ 
whichTOMGlobalsHd] = (TeerOffMGlobalsHdl) 
Ge tResource( TEAR_OFF MENU_GLOBALS_TYPE, 
C*whichMenu2-?menuID); 


if((ResErr == noErr) && (whichTOMGlobalsHdl != nil)) ( 
/* Lock the TearOffMenuGlobals structure so it can 
be dereferenced safely. */ 
HLockCwhichTOMGlobalsHdl); 
tearOffMGlobals = *whichTOMGlobalsHdl; 


/* Dispatch according to the message received from 
the Macintosh ROM. Use multiple ‘if’s 
rather than “switch” to avoid linking of 400% 
bytes of runtime code. */ 


if(message == mDrewMsg) ( 
CallPescal(menuRect, 
› drewMenuProc); 
/* Hilite currentItem here instead of in 
ChooseItem(). It may not be called son. */ 
CallPascal(menuRect, (tear Of fMGlobals)- 


(teerOf f MGlobals)- 
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^currentItem, true, 
CtearOf fMGlobals)->hiliteItemProc); 
/* Let ChooseItemC) know currentItem has been 
hilited. */ 
CtearOffMGlobals)->itemHilited = true; 


else if (message == mChooseMsg) ( 
ChooseItemCtearOffMGlobals, menuRect, hitPt, 
whichI tem); 


else if(message == mSizeMsg) ( 
/* Calculate the menuRect from the 
paletteWindow’s portRect. */ 

C*whichMenu2-? menuW idth 
= (CtearOffMGlobals)-?paletteWindow) 
-)portRect .right 
- CCtearüf fMGlobals)-> paletteW indow) 
-)portRect . left; 
C*whichMenu)-»menuHeight 
= (Ctear0f fMGlobals)->paletteW indow) 
-»portRect .bottom 
- (Ctear0f fMGlobals)-> palettewW indow) 
-ӘрогіКесі. top; 


) 
HUnlockCwh ichTOMG lobalsHdl); 
RestoreA5(); 


/%-----------------<Н005Е ITEM 


If the mouse is within the menuRect, ChooseItemC) will call 
the application to find in which item the mouse is currently 
located. The application is also called to hilite or unhilite 
а single item. If the mouse is outside the menuRgn ChooseItem 
will call DragMenuC). The menuRgn is defined as an area made 
up of the menuRect with а margin and the menu bar. */ 


void ChooseItemCtearOffMGlobals, menuRect, hitPt, 
whichItem) 

TearOffMGlobalsPtr tearOffMGlobals; 

Rect *menuRect; 

Point hitPt; 

short *whichItem; 


short saveltem; 

short hiliteItem; 

Point mousePt; 

Rect marginRect; 

RgnHandle menuRgn; 

RgnHandle tempRgn; 
QuickDrawGlobals *qdGlobals; 


/* Set up pointer to QuickDraw’s global variables. */ 
qd6lobals = (QuickDrawGlobals *)(*(Bute **)CurrentA5 


- (sizeof (QuickDrawG lobals) 
- sizeof (GrafPtr))); 


saveItem = *whichI tem; 
hiliteItem = *whichItem = 0; 


/* If the hitPt is empty, the Menu Manager is calling 
Tear Of fMDEF repeatedly to flash the item. */ 


ifCChitPt.h != Ø) && ChitPt.v != 0)) ( 
if(PtInRect(hitPt, menuRect)) ( 
mousePt.h = hitPt.h - menuRect-? left; 
mousePt.v = hitPt.v - menuRect-> top; 


hiliteItem = *whichItem = CallPescalWCmousePt, 
CtearOf fMGlobals2-»f indI temProc); 


if (CtearOffMGlobals)-)> itemHilited) ( 
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saveltem = CtearOffMGlobals)— currentIten; 
CtearOffMGlobals)-> itemHilited = false; 


else ( 


ifC!CtearOffMGlobals)->itemHilited) ( 
hiliteItem = CtearOffMGlobals)- currentItem; 
(teerOf f MGlobals)— itemHilited = true; 


) 


) 
ifCsaveItem != hiliteItem) ( 
/* Unhilite the old item. */ 
CallPescal(menuRect, saveltem, false, 
CtearOf fMGlobals)- hiliteItemProc); 
/* Hilite the new item. */ 
CellPescal(menuRect, hiliteItem, true, 
Ctear0ffMGlobals)-»hilitel temProc); 


/* Calculate the menu region. if the mouse is outside 
this region tear off the menu. */ 

marginRect = *menuRect; 

marginRect. left -= TEAR_OFF_MARGIN; 

marginRect.bottom += TEAR OFF MARGIN; 

marginRect.right += TEAR_OFF_MARGIN; 

RectRgn(menuRgn = NewRgn(), &marginRect); 


RectRgn(tempRgn = NewRgn(), &qdGlobals-»screenBits bounds); 


if CtearOf fMGlobals-?environment-»machineType 
< envMachUnknown) ( 
/* Arrggh! Someone has the 64K ROMs. */ 
(*tempRgn2— rgnBBox.bottom = 20; 


else ( 
C*tempRgn2)-— rgnBBox.bottom = MBarHeight; 


UnionRgn(menuRgn, tempRgn, menuRgn); 


ifCIPtInRgnChitPt, menuRgn)) ( 
DragMenu(CtearOffMGlobals, hitPt, whichItem, 
menuRgn, tempRgn, qdGlobals); 


DisposeRgn( tempRgn); 
DisposeRgn(menuRgn); 


) 
%------------ОҒА MENU 


ОгадМепиС) draws an outline of the paletteWindow аз the 
mouse is moved outside the menuRgn. If the mouse button is 
released outside this region, DregMenuC) will set whichItem to 
-1 end exit. */ 


void DragMenuCteerOffMGlobals, hitPt, whichItem, 
menuRgn, saveRgn, qdGlobals) 

TearOffMGlobalsPtr tearOffMGlobals; 

Point hitPt; 

short *whichI tem; 

RgnHandle menuRgn; 

RgnHandle saveRgn; 

nn *qdGlobals; 


PenState savePen; 

long finalTicks; 

Rect windowRect; 
RgnHendle structureRgn; 
short hOffset; 

Point oldMouse; 

Point newMouse; 
RgnHendle dragRgn; 


GetPenState(&savePen); 
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PenSizeC1, 1); 
PenMode(notPatXor); 
PenPat(qdG lobals-> gray); 


/* Since paletteWindow may not be visible, its 


window frame. */ 
windowRect 
= (tearOffMGlobals-»paletteWindow)-?portRect; 


/* Correct windowRect if top, left of portRect isn’t 
0,0. */ 

OffsetRect(&windowRect, -windowRect. left, 
- windowRect. top); 


windowRect right += 3; 
windowRect .bottom += PALETTE_TITLE_BAR_HEIGHT + 3; 
RectRgn(structureRgn = NewRgn(), &windowRect); 


hOffset = windowRect.right / 2; 


/* Next, calculate the frame’s drop shadow. */ 
windowRect.top += PALETTE_SHADOW_INDENT ; 
windowRect. left += PALETTE_SHADOW_INDENT ; 
windowRect .bottom += 1; 

windowRect. right += 1; 

RectRgn(saveRgn, &windowRect); 


/* Combine frame, shadow to calculate structure. */ 
UnionRgnCstructureRgn, saveRgn, structureRgn); 


GetClipCsaveRgn); 
SetClipCGreyRgn); 


oldMouse = newMouse = hitPt; 


CopyRgn(structureRgn, dregRgn = NewRgn()); 
OffsetRgnCdregRgn, newMouse.h - hOffset, newMouse.v 
- PALETTE OFFSET); 


/* Drew first dreg outline. */ 
FreneRgnCdregRgn?; 


/* Mimic DragGrauRgn() by staying in а loop until the 
mouse button is releesed or the mouse is inside the 
again. */ 


do ( 


/* Don't erase old drag outline if the mouse 
hasn’t moved. */ 


if(!EqualPt(newMouse, oldMouse)) ( 
/* Erase old drag outline. */ 
FrameRgn(dragRgn ); 
CopyRgn(structureRgn, dregRgn?; 
Of fsetRgnCdragRgn, newMouse.h - hOffset, 
newMouse.v - PALETTE. OFFSET); 


/* Draw new drag outline. */ 
FrameRgn(dragRgn ); 


/* Keep drag outline from flickering. */ 
Delay(2, &f inalTicks); 


oldMouse = newMouse; 
Ge tMouse (&newMouse ); 


) 
while(WaitMouseUp() && !PtInRgn(newMouse, menuRgn)); 


/* Erese final drag outline. */ 
FreneRgnCdragRgn?; 


ifC!PtInRgnCnewMouse, menuRgn)) ( 
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portRect 
must be used to calculate structureRgn. First, calculate the 


menuRgn 


Ctear0f fMGlobals2-?position.h 
»rgnBBox.left + 1; 

Ctear0f f MGlobals)-»position.v 
"rgnBBox.top + 11; 


/* Tell application the menu wes torn off. */ 
*whichItem = MOVE. PALETTE ITEM; 


DisposeRgn(structureRgn); 
DisposeRgn(dragRgn); 


SetCl ipCsaveRgn); 
Se tPenState(&savePen); 
/* 
TEAROFF PALETTE 
version 1.8 
by Don Melton and Mike Ritter 


Copyright (C)1987, 1988 by Impulse Technologies, 
Inc., 811 rights reserved. 


Tear OffPalette.project.r 
Font: Monaco, 9 point 
Tab setting: 


2 
Compiler: MPW Rez 2.0 */ 


%---------------ІМІШОЕ TYPES %/ 
include “Турев.г” 

/х 

TYPE DEFINITIONS */ 

type ‘ТОРО’ as ‘STR '; 
/*——— P RESOURCE DEFINITIONS */ 


resource ‘BNDL’ (128) ( 
‘ТОРО’, 
0, 
( 
ICNS’, 
( 


resource ‘FREF’ (128) ( 
APPL’, 
0, 
"s 
); 
еге ‘ICN®’ (128, purgeable) ( 


/* Date */ 

$"FFFF FFEO 8000 0030 8000 0030 EFBF FFF" 
$^8880 0030 EBBF FFFO 8880 0030 EFBF FFF0" 
$^8000 0030 B1FF FFFE ҒҒ00 0002 81ВА AAAA” 
$^8128 0003 81ВА AAAB 8100 0003 BIFF FFFF^ 
$^8100 0003 8100 0003 8100 0003 8100 0003" 
$^8100 0003 8100 0003 8100 0003 8100 0003" 
$^8100 0003 8100 0003 В1ЕЕ FFFF 803F ҒҒҒҒ” 


Gdregig- 
(вол 
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) 
}; 


$"8000 0030 8000 0030 FFFF FFFO 7FFF FFFO", 


/% Mask %/ 
$^FFFF FFEØ FFFF FFFØ FFFF FFF0 FFFF FFF" 
$^FFFF ҒҒҒЙ FFFF FFFÜ FFFF FFFÜ FFFF ЕРО" 
$^FFFF FFFÜ FFFF FFFE FFFF FFFE FFFF FFFE^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF” 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF” 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFF 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$^FFFF FFFO FFFF FFFØ FFFF ҒЕҒй TFFF FFFO" 


resource ‘PAT#’ (128, preload) ( 


( 


/* 64 elements */ 


7 
$^80", 
$^8200 0000 08", 
$8800 0000 08", 
$8800 0000 88", 
$^8800 2000 88", 
$"8800 2000 8800 02", 
$^8800 2200 8800 02", 
%%8800 2200 8800 22", 
%”А800 2200 8800 22", 
$"A800 2200 ВАФО 22", 
$^AA00 2200 BACB 22", 
$"AA00 2200 AADO 22", 
$^AA00 A200 AADO 22", 
%”ААОЙ A200 AADO 2A”, 
$ AADO АА00 AADO АА”, 
$^АА40 АА00 АА00 ДА”, 
%”АА40 АА00 AADA АА”, 
$"AM4 АА00 АА04 АА», 
$^АА44 AA00 AMA ЛА”, 
$"AMA АА10 AMA АА”, 
$"AMA АА10 AMA M1", 
$^АА44 АА11 AMA M1", 
%”АА44 АА11 AMA M1", 
%”АА54 АА11 АА44 M11", 
$^ААБ4 АА11 АА45 АА11", 
%”АА55 АА11 АА45 A 11" 
$^АА55 АА11 АА55 AA11" 
%”АА55 АА51 AA55 M1", 
$”AA55 ААБ1 АА55 АА 15", 
$”AA55 АА55 АА55 АА 15", 
$”AA55 АА55 AA55 ААББ", 
%”ЕА55 АА55 ААББ АА55”, 
$"EA55 АА55 АЕ55 АА55", 
$"EE55 АА55 АЕ55 АА55", 
$^ЕЕ55 АА55 ЕЕ55 AA55", 
%”ЕЕ55 ВА55 ЕЕ55 АА55", 
%”ЕЕ55 ВА55 EE55 А855", 
%”ЕЕ55 ВВ55 ЕЕ55 А855", 
%”ЕЕ55 ВВ55 EE55 8855", 
$^ЕЕ55 ВВ55 ЕЕ55 8855", 
$^FE55 BB55 EF55 BB55", 
$^FF55 ВВ55 EF55 BB55", 
$^FF55 ВВ55 FF55 BB55", 
$"FF55 FB55 FF55 8855", 
$?FF55 ЕВ55 FF55 BF55", 
$“FF55 FF55 FF55 BF55", 
$“FF55 FF55 FF55 РЕ55", 
$^FFD5 FF55 FF55 FF55", 
$^FFD5 FF55 FF5D FF55", 
$“FFDD FF55 FF5D FF55", 
$“FFDD FF55 FFDD FF55", 
$*FFDD FF75 FFDD FF55", 
$"FFDD FF75 FFDO FF57", 
$^FFDD FF77 FFDD FF57", 
$^FFDD FF77 FFDD FF77", 
$“FFFD FF77 FFDD FF77", 
$“FFFD FF77 FFDF FF77", 
$^FFFF FF77 FFDF FF77", 
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); 


$^FFFF FF77 FFFF FF77", 
$^FFFF FFF7 FFFF РЕТТ”, 
$^FFFF FFF7 FFFF FFTF^, 
$°FFFF FFFF FFFF ЕРТЕ”, 
$°FFFF FFFF FFFF FFFF^ 


) 


resource 'STR ” (128, preload) ( 


7 


“Untitled” 


resource “РІСТ” (128, preload) ( 


1270, 
(0, 0, 83, 99), 

$”1101 A000 8201 000A 0000 0000 0200 0240" 
$"9800 OEOD 0000 0000 5300 6800 0000 0000" 
$*5300 6300 0000 0000 5300 6300 000С ҒЕ00" 
$"0680 0000 4000 0020 Ғ000 OCFE 0006 8000" 
$0040 0000 20FD 000Е ҒЕ00 0880 0000 4006" 
$0020 0380 ҒҒ00 0-08 OF3E 7080 ІҒС0 4069" 
$°C020 0280 ЕҒ00 0-08 0800 1080 Е030 4099" 
$*2020 0380 ЕҒ00 0-08 0800 1081 0008 4009" 
$*2826 0380 ҒҒ00 ФЕРЕ 0008 8200 0840 4934" 
$2003 80ЕЕ 000Е FEØ 0884 0008 4049 2420" 
%%0380 FFØØ FOB 0800 1084 0030 4140 2420" 
$*0380 FFØØ ØFØB 0800 1084 01С0 4260 0420" 
$^lFFÜ FFØØ 0-08 0800 1083 8Е00 4220 0820" 
$1010 ҒҒ00 0Ғ08 0800 1086 7000 4100 0820" 
$^1РЕ0 ЕҒ00 ОЕРЕ 0008 8540 0040 8008 2010" 
%”10ҒҒ 000Е ҒЕ00 0883 8000 4080 1020 1010" 
$"FFO0 0-08 0800 1080 8000 4040 1020 1010" 
$2FF00 0-06 0800 1080 8000 40ЕЕ 2001 1550" 
$“FF00 OFOB 0ЕТС Ғ081 0000 4010 2020 2ABO" 
$"FFO0 GEFE 0008 8000 0040 1020 207F EOFF" 
$"000C ҒЕ00 0680 0000 4000 0020 Ғ000 0СҒЕ” 
$"0006 8000 0040 0000 20-0 0005 ЕБЕЕ 01Е0" 
%%000С ҒЕ00 0680 0000 4000 0020 Ғ000 OCFE" 
$"0006 8000 0040 0000 20-0 0000 0900 0Ғ00" 
$8000 0040 100 21FD 000Е 0А00 0880 8000" 
$"0040 2200 2040 ҒЕ00 OEOA 0010 8080 QTFO" 
$4026 0021 15ҒЕ 000Ғ 0800 1900 8008 1040" 
$^2800 2043 80ҒҒ 000Ғ 0800 2700 8010 3840" 
$^32С0 2104 40FF 000Ғ 0800 2200 8020 5840" 
$*2276 200F EØFF 000Ғ 0800 4200 8040 8040" 
$4238 2008 20FF 000Ғ 0800 4400 8081 6040" 
$^851C 2009 EOFF 000Ғ 0800 8400 8102 041" 
%%021С 2009 20FF ØØØF 0800 8800 8205 8042" 
%%003С 2009 EOFF 000Ғ 0801 0800 87FB 0042" 
$*005С 2009 20FF GOOF 0801 1000 840E 0041" 
$"009C 2009 EOFF 000Ғ 0801 Е000 840С 0040" 
$*811С 2009 EOFF 000Ғ 0801 (000 87Ғ8 0040" 
%%421С 2008 20FF 000Е 0801 8000 8000 0040" 
$^2418 2008 20FF 000Ғ 0801 0000 8000 0040" 
$^1810 200F EOFF 000С ҒЕ00 0680 0000 4000" 
%%0020 FDOO 0СҒЕ 0006 8000 0040 0000 20Ғ0” 
%%0005 F5FF 01Е0 000С ҒЕ00 0680 0000 4000" 
$0020 Ғ000 0СҒЕ 0006 8000 0040 0000 20Ғ0” 
$"000C ҒЕ00 0680 0000 4000 0020 Е000 00ҒЕ” 
$0007 8000 0040 0000 2003 ҒЕ00 ФЕРЕ 0008" 
$^87FF Ғ840 1Ғ80 200C COFF 000Е ҒЕ00 0884" 
$0008 4060 6020 3030 ҒҒ00 0Ғ08 0С00 0084" 
$0008 4180 1820 COOC ҒҒ00 OFOB 0300 0084" 
$2008 4100 0820 8004 ҒҒ00 0Ғ0В 00С0 0084" 
$"0008 4200 0420 8004 ҒҒ00 OFOB 0030 0084" 
$*0008 4200 0420 8004 ҒҒ00 OFOB 000С 0084" 
$0008 4200 0420 8004 FF00 0Ғ08 0003 0084" 
$0008 4200 0420 8004 ҒҒ00 0Ғ0В 0000 С084" 
$0008 4100 0820 8004 ҒҒ00 ØFØB 0000 3084" 
%%0008 4180 1820 COOC ҒҒ00 ФЕРЕ 0008 8400" 
$0840 6060 2030 30FF 000Е ҒЕ00 0887 FFFB" 
$"401F 8020 0СС0 ҒҒ00 ODFE 0007 8000 0040" 
$0000 2003 ҒЕ00 OCFE 0006 8000 0040 0000" 
$^20FD 000С ҒЕ00 0680 0000 4000 0020 Ғ000" 
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%”0СҒЕ 0006 8000 0040 0000 20FD 0005 ҒОҒҒ” 
$^01E0 000С ҒЕ00 0680 0000 4000 0020 FDOO" 
$°0СЕЕ 0006 8000 0040 0000 20Ғ0 000С FEOO" 
$^0680 0000 4000 0020 Ғ000 0009 ОТЕЕ Е080" 
%%0000 4000 0020 Ғ000 0009 0618 6081 FFEO" 
$^"4000 0020 Ғ000 0-08 0418 2082 0010 40Е0" 
$^7020 0ҒЕй ҒҒ00 0-08 0418 2084 0008 4118" 


$* 1603 0000 0378 Ғ000 0040 9188 4208 C310" 
$"44C4 3108 2444 0016 0300 0001 FOFD 0000” 
$“E1F®@ FOE7 1CC1 EØFC 781E 1С7С 7800 06ҒЕ” 
%%0000 EOEF 0006 ҒЕ00 0040 ЕҒ00 А000 83ҒҒ” 


resource “0100” (128, preload) ( 


$^8820 1020 ҒҒ00 0Е08 
%%”04ҒЕ 20FF 000Ғ 0800 
$2040 20ҒҒ 000Ғ 0800 
$2080 20FF 000Ғ 0800 
92100 10ҒҒ 000Ғ 0800 
$^2080 08ЕЕ 000Ғ 0800 


0018 0084 0008 4207" 
1800 8400 0842 0004" 
1800 8400 0842 0004" 
1800 8400 0842 0004" 
1800 8400 0841 0008" 
1800 8400 0841 0010" 


(0, 0, 160, 418), 
dBoxProc, 
invisible, 
noGoAway, 

0x0, 


$°2040 04ЕЕ 000Ғ 0700 1800 8400 0840 80ҒЕ” 

$^2000 02ҒҒ 000Ғ 0800 1800 8200 1040 60С0" 

$^201F FEFF 0000 0900 1800 81FF Е040 1Ғ00" 

$^20FD 0000 0900 ТЕ00 8000 0040 0000 20Ғ0” 

$"000C ҒЕ00 0680 0000 4000 0020 Ғ000 0СҒЕ” 

$^0006 8000 0040 0000 20-0 000С ҒЕ00 0680" 
%%0000 4000 0020 Ғ000 А200 B3FF" 


resource ‘PICT’ (129, purgeable) ( 


858, 

(0, 0, 51, 166), 

491101 A000 8201 000A 0000 0000 0200 0240" 
$"9800 1600 0000 0000 3300 A800 0000 0000" 
$*3300 A600 0000 0000 3300 A600 0006 ҒЕ00" 
$0080 ЕҒ00 0703 0000 0140 ЕҒ00 0103 0000" 
%%0220 ЕҒ00 0703 0000 0410 ЕҒ00 0703 0000" 
$^0808 ЕҒ00 0703 0000 1004 ЕҒ00 0703 0000" 
$"2002 EFØØ 0703 0000 4001 ЕҒ00 0804 0000" 
$^8000 80-0 0008 0400 0100 0040 Ғ000 0004" 
$"0002 0000 20FB 0001 0180 Ғ800 0004 0004" 
%%0000 10-8 0001 0-80 Ғ800 0004 0008 001С” 
$^08ЕВ 0001 3Ғ80 Ғ800 0С04 0010 00ҒС 04Ғ8” 
%%0000 ОТЕТ 000С 0400 2000 ҒС02 FBOO 0007" 
$^F700 0С04 0040 00ҒС 0ІҒВ 0000 07Ғ7 0000” 
$0500 8000 Ғ800 80ҒС 0000 ØFF7 0000 0501" 
$0000 F800 40ҒС 0000 OEF7 0000 0502 0000" 
$"F800 20FC 0000 EFT 0008 0304 0001 ҒОҒА” 
$"0000 BEF7 0012 0608 0001 FOTO 703С 787C” 
$21007 0Е07 FOIF ҒА00 130Ғ 1000 ВІҒІ ҒІҒ4" 
$*FCF8 FETC OF 1E 1ЕЕ0 7F80 FBOO 130F 2000" 
$"01E7 F3F3 FFF9 SEFC 0Е1С 3871 C380 ҒВ00" 
%”130Е 4000 01ЕС E673 ЗЕЗЗ 0Ғ9С 0Е1С 3031" 
$25380 FBOO 130F 8000 01Е0 EC76 B83E 0Е1С” 
$"0E1C 7023 8380 FB00 130F 4000 03С0 Ғ870” 
$^383С @E3C 1Е 1С 7003 8780 Ғ800 120Е 2000" 
%%03С1 FOFB 7878 0Е38 1C3C 7807 OFFA 0012" 
$"0E30 0003 СІҒй F778 780Е 381C 383F CT3C" 
$"FA00 120Е 1800 0381 EØF7 7070 1638 3С38" 
$“3FE7 EOFA 0011 000С 0003 81Еб Ғ670 701С” 
$"183C 3807 FFF9 0011 0006 0000 03С1 ECFO" 
$"F038 7078 3800 FEF9 0011 0003 0000 03С1" 
$"E8FÜ Е038 70Ғ8 7800 ТЕҒ9 0011 0401 8007" 
$^03С1 FEEO 0570 7188 70С0 ТЕҒ9 0012 0:00" 
$^CO0F 8381 COEO Е070 F338 71С0 6Е03 ҒА00" 
$2 120Е 0060 0Ғ87 83C1 EDEO EOF6 3877 COCF" 
%”06ҒА 0012 0Е00 300F 8783 СІҒ9 F1CO ЕСТЕ” 
$27CE3 8Ғ8С FAO0 120Е 0018 0Ғ87 0881 ҒІҒҒ” 
$^00Е8 7C78 FFO7 F8FA 0012 0:00 0С07 071В” 
$^80C1 ҒС00 6070 607С 03Е0 ҒА00 0807 0006" 
$"0000 3С00 03С0 F300 0807 0003 0000 7800" 
%%03С0 F300 0807 0001 8000 FOOD 03С0 F300" 
91715 0000 С001 Е000 03С1 ҒІҒй 78Е7 1СЕ0" 
$^Е0ЕО 3COF 1С7С 3000 1715 0000 6003 С000" 
$20381 5090 8842 0С41 1840 4611 0824 4400" 
%ғ1715 0000 3007 8000 0780 4081 0042 0/42" 
$^0840 8220 0820 4000 1715 0000 180Ғ 0000" 
$^0780 40E1 00ТЕ 0A42 0840 8220 0838 3800" 
6,1715 0000 0С1Е 0000 0780 4081 0042 0942" 
$20840 8223 8820 ØCØ 1715 0000 063С 0000" 
$20780 4081 0042 0942 0840 8221 0820 0400" 
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гв, 
); 
resource 'DITL^ (128, preload) ( 
(10, 10, 42, 42), 
Icon ( 


enabled, 
128 


), 

(14, 52, 30, 408), 

StaticText ( 
enabled, 


*TearOffPalette by Don Melton and Mike Ritter” 


) 

(30, 52, 46, 408), 

StaticText ( 
enabled, 


"01987, 1988 by Impulse Technologies, Inc." 


), 

(56, 10, 72, 408), 

SteticText ( 
enabled, 
"Designed Гог MacTutor: The Macintosh “ 
“Programming Journal” 


(72, 10, 88, 408), 

StaticText ( 
enabled, 
“Compiled with LightspeedC™ version 2. 15” 


) 

(98, 190, 130, 408), 

StaticText ( 
enebled, 


“*Sure. We can do that. We don’t even have to ^ 


“nave а reason."^ 


), 
(134, 190, 150, 408), 
StaticText ( 

enabled, 

*Call us at (408) 296-6110” 


), 
(98, 10, 149, 176), 
Picture ( 
enabled, 
129 
) 
) 
); 


resource ‘ТОРО’ (Ø) ( 


"ТеагОГЇРа1е{{е by Don Melton and Mike Ritter, ^ 


"01987, 1988 by Impulse Technologies, Inc., * 
“all rights reserved." 


7 
data ‘TOMG’ C131, preload) ( 


$"0000 0000 0000 0000 0000 0000 0000" 
$"0000 0000 0000 0000 0000 0000 0000" 
. 


д 
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data 'TOMG^ (132, preload) ( 
$"0000 0000 0000 0000 0000 0000 0000" 
$^0000 0000 0000 0000 0000 0000 0000" 


4 


data ‘TOMG’ (133, preload) ( 
$^0000 0000 0000 0000 0000 0000 0000" 
%”0000 0000 0000 0000 0000 0000 0000" 


7 


resource ‘MENU’ (128, preload) ( 
128, 
textMenuProc, 
Ox7FFFFFFD, 
enabled, 


apple, 
( 


"About TearOffPalette.", noIcon, *", *", plain, 
*-*, nolcon, *^, *# plain 


) 
у 
resource 'MENU^ (129, preload) ( 
129, 
textMenuProc, 
QxTFFFFFF5, 
enabled, 
“File”, 
“New”, noIcon, “№, е, plain, 
*-^, noIcon, “”, *", plain, 
“Close”, noIcon, "W^, **, plain, 
*-^, nolcon, ^^", **, plain, 
“Quit”, noIcon, “Q”, “? plain 
); 
resource ‘MENU’ (130, preload) ( 
130, 
textMenuProc, 
Ox7FFFFFFD, 
enabled, 
co 
“Undo”, noIcon, “7%, *", plain, 
“-*, nolIcon, "^, *^, plain, 
“Cut”, noIcon, ^X^, *", plain, 
“Сору”, noIcon, “С”, “”, plain, 
“Paste”, noIcon, “У”, *", plain, 
“Clear”, noIcon, **, **, plain 
); 
resource “MENU” (131, preload) ( 
131, 
128, 
allEnabled, 
enabled, 
“Tool’, 
/* 16 elements */ 
**^, поїсоп, *", *", plain, 
"жи, nolcon, *^", “”, plain, 
**^, noIcon, “*, "^, plain, 
"ж, nolcon, ””, *", plain, 
«ж? nolIcon, "^, "^, plain, 
“*# noIcon, *^, “”, plain, 
**", поїсоп, *", “”, plain, 
“ж”, nolcon, “”, **, plain, 
"жг, noIcon, "^", *^, plain, 
“x”, поїсоп, *^, *^", plain, 
“x”, nolIcon, *^, *^, plain, 
“*# noIcon, *^, "^, plain, 
“x”, поїсоп, 4”, “”, plain, 
“жи, поїсоп, *^, *^, plain, 
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**^, nolcon, *^, “”, plain, 
“хи, поїсоп, ””, **, plain 


132, 
128, 


allEnabled, 


enabled, 
Pattern”, 


/* 64 elements */ 
“x” noIcon, 
**^ nolcon, 
“x” noIcon, 
“x” nolcon, 
**^ nolcon, 
“x” nolcon, 
“x” nolcon, 
“x” nolcon, 
“x” nolcon, 
«x», nolcon, 
“x” noIcon, 
“x” noIcon, 
“x” nolcon, 
**^, nolcon, 
“3% nolcon, 
“x” nolcon, 
“x” nolcon, 
**^, nolcon, 
“x” nolcon, 
“x” nolcon, 
“х, nolcon, 
“Ж” nolcon, 
их’, nolcon, 
"х, nolcon, 
“x” nolcon, 
“ж”, nolcon, 
“x” nolcon, 
“x” nolcon, 
**^, nolcon, 
^x^, nolcon, 
их’, nolcon, 
«хг, nolcon, 
*x^ nolcon, 
**^ nolcon, 
еж, nolcon, 
“x” nolcon, 
“x” noIcon, 
“x” nolcon, 
«х, nolcon, 
“х2, nolcon, 
“x” nolcon, 
“x” nolcon, 
“x”, noIcon, 
“x” nolcon, 
“x” noIcon, 
“x” nolcon, 
**^ nolcon, 
“x” nolcon, 

, holcon, 

, hoIcon, 

, holIcon, 

, nolcon, 

, hoIcon, 

, noIcon, 
“хг, nolcon, 

7 

д 

М 

2 

7 

2 

2 


ех» 
ехе 
ex» 
"жи 
xe 
"x 


“xe 
"ex 
“xe 
"ex 
"x 
ex 
"ex 


< aa aa 3332332332 2 ха a aa aa aa aa > а > > > >a > > x > RRR RAAR RR R R A R RRR 
V x t t & & t t +c t t SF + & ç k + ы t F w ъъ £ ( £&£€ ok oi o oi t ы ы kt t * 
“М “ы * мм м w мм I I w* ъъ мм w* ъъ w*< м w* ww w* w w w* м * . -. . w -. < < ` ` ` ы ` - ` 


аа 2 2 aa aa 2 a а а аэ з аа а 
ч t t t t t t +< < < ee “< “< * 
oV w S. S.S SS S S. S. S ` ` S . 


noIcon, 
noIcon, 
noIcon, 
noIcon, 
noIcon, 
noIcon, 
noIcon, 


R 2 2 2 а 
z = t t k 


з 
t 
“М w w* м * * . 


resource ‘MENU’ (132, preload) ( 


plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
plain, 
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exo "m А 
“x” noIcon, *" к, plain, Tem noIcon, ud ite plain, naa! isa on on aa 
4 i d e» “x”  noIcon, *^, *^ plain, , hoicon, 4 ‚р кч 
"җә, noIcon, , ) plain E, nol sn: ЕР plain ex» noIcon, "d. 2. plain, 
«жә? nolcon, 4%) "", plain, юго АРЫЛДЫ, 
); “ж”, nolcon, "*, "", plain, еж”, noIcon, 4%, “7, plain, 
| a Moss КЕ ee plain, *** molcon, ””, id plain, 
resource ‘MENU’ (133, preload) ( PM nion. ИН ЗР, plain «х», noIcon, P a. plain, 
133, d nO cf. S. aig! plain, «ж», noIcon, Tu 40; plain, 
128, ғ.” ООВ. e» ae plain, “x” nolcon, к, plain, 
allEnabled, 4%»: О. WR 4». plain, “x” noIcon, ©”, *^, plain, 
cr еке” noIcon, **, “=”, plain, **^, noIcon, *^, 4%, plain, 
“Color’, exe I on. AE d plain, “x” noIcon, "^, *^, plain, 
cn 12 i axe” noc еш ет plain, “x”, noIcon, *", “%, plain, 
"xs noIcon, белі”, plain, es а ЖЕ ЖЕК. lan exe nolcon, e» e» plain, 
**" nolcon, e» nh plain, 222) по1соп, КЕ ДӨЖ, if od «ж» го]соп, e» а, plain, 

xe Ки: an lain * ; noIcon, , , Plain, 4 we» w I 
) noIcon, , ‚ P 12 exo Icon, *^, *^ plain кә, noIcon, ; ; plein, 
es nolcon, *", cr plain, Ew ie e РР. plain, «ж» nolcon, e» e» plein, 
*t^ nolcon, e» та plein, dis! ded DU. Me а, е» noIcon, “”, “”, plain, 
«ж» nolcon, e» е2 plain, exa! бы амы ved) blan. «жә, nolcon, *^, “”, plain, 
“x” nolcon, e», е», plain, fn c ЖА ДНК, piain. “x” по[соп, “2, *", plain, 
“x” nolcon, “”, .. plain, ar е 254 ^2) lain. “x”  noIcon, **, “” plain, 
еж’, noIcon, *^, **, plain, nd Lea on aw plain, **^. noIcon, **, **, plain, 
ext noIcon, “*, 64. plain, me. dieses RO ай Sein: exo nolcon, .. .. plain, 
“x”, nolcon, **, “*, plain, ex» авй, e» пи, plain, “x”, nolIcon, **, *^, plein, 
«ж molcon, “2”, *", plein, м 7. GEM plain. «хә nolcon, *^, **, plain, 
“x”, noIcon, **, **, plain, exe’ nolcon, 2 «^! plein, «хә, noIcon, **, *", plain, 
**" molcon, “”, **, plain, е Ды анд, NM АА «жә nolcon, 4”, “”, plain, 
«хә noIcon, “7, *", plain, йик, d wal pe! S ех» nolcon, 4”, "^, plein, 
ex» поїсоп, .. .. plain, iss е. ме ай а, ex» noIcon, .. тә, plein, 
«ж nolcon, **, ~, plain, vis M qu. slain, «ж» nolcon, “> “ plein, 
ех. поїсоп, е ки. plain, 452! id AE et. plain, «хо, поїсоп, e^ 42. plein, 
xe noIcon, .. Шай plain, a 1 ME plain, exe noIcon, .. .. plain, 
one noIcon, .. т»: plain, RS. A ae Қ. plain, exo noIcon, .. .. plain, 
**" nolcon, “?”, “*, plain, БЕ, decal n lain “x” nolcon, **, **, plain, 
ех» nolcon, *", *^, plain, рар. йы дд, zb lol D lain. “x” nolcon, *^, *", plain, 
"җә, nolcon, .. e plein, Mar doin n. plain; ex поїсоп, "^ "^ plain, 
**" nolcon, **, **, plein, sae? cm Рей Ban “x” nolcon, “”, **, plain, 
"xs nolcon, *^, ““ plain, E. E ss 23 plain, xe noIcon, е”. .. plain, 
«жә nolcon, . “” plain, 22 о ДО plain, **^ nolcon, "", ““ plain, 
«ж» nolcon, “”, “> plain, EE е K es iain, «ж noIcon, “”, “”, plain, 
еж» nolIcon, *^, *", plein, bor ira, n NM plain. **" nolcon, *", **, plain, 
ex поїсоп, "^ i plain, Mr дыд, кк "ait lain! exo noIcon, .. .. plain, 
exo noIcon, .. 54. plain, is! 222 P а-а plain, xe nolcon, “”, n plain, 
ех» nolcon, “”, М2 plain, x. а, EA ЖӘН, plain, “x” noIcon, “”, “”, plain, 
“х2, noIcon, 4%, 4%, plain, exa Saleen: ev ae plain, “x”, nolcon, 4%, “*, plain, 
“ж”, nolcon, “”, **, plain, exa ДЕНЕ, on ae plain, “x”, noIcon, “”, “*, plain, 
“x” nolcon, *^, *", plein, ir Mood, EP plain. “x” nolcon, е, *^, plain, 
“x”, nolcon, “”, “°, plein, xe Дз, e» an plain, **^, noIcon, 4”, **, plain, 
е nolcon, **, **, plain, ut а. КЕС lain. “*# nolcon, е, “”, plain, 
"xs поїсоп, *^, “”, plein, "me. йи ена, ШК ЖИЕ, ео "X^, nolcon, *^, *", plain, 
ех» nolcon, “*, Tes plein, n ian. e»! an а, “x” nolIcon, *", “” plain, 
"җә, по1соп, .. = plain, А Ss. n | ii ШК m. plain, xe noIcon, .. .. plain, 
еж» npolcon, “”, “”, plain, ни irs NAE ЖЕН; а, “x” nolcon, *", *", plain, 
«ж» noIcon, 4. e plain, ns Mu "a. plain, “x” nolcon, ">, 4” plein, 
еж» noIcon, е. ео plain, 22 5. va! ual alain, “x” nolcon, ~, е” plain, 
«хә, noIcon, С eT. plain, yee ics ie СУ, plein, ехо, nolcon, .. e plein, 
«жә nolcon, “”, "e plain, e. TIC p ДЕК, plain, **" nolcon, **, "”, plain, 
xe поїсоп, **, еа. різіп, ы! Ec a wwe. plain; ех» nolcon, e» 4” plain, 
xe поїсоп, .. .. plain, ni би ида. КРЕ. piain, ez”, nolcon, *", ““ plain, 
**^, noIcon, *^, “7, plain, 5e x e»! cv plain, **^, noIcon, **, *", plain, 
“x” nolcon, **, “”, plain, ex»! н. ov an plain, “x” noIcon, 4”, *", plain, 
"xs noIcon, .. 48. plein, ne Mes X AM. plain, exe nolcon, "ә, .. plain, 
"е noIcon, *^, *", plein, ha о ДЕК plain. «хә molcon, "", *", plein, 
ехо, noIcon, „сег, plein, eso 22 ЖЕ ny plain. ех», nolcon, “°, *^ plein, 
ее nolcon, “2, *", plain, exa Дои na ax plain. «жә nolcon, *", “”, plain, 
к, nolcon, в е; plein, xe о e» cn plain, ж”. по[соп, ШЕ” те plain, 
**" molcon, .. 4, р1аїп, 22 Шы ЖА "I plain. «ж» nolcon, “2”, “”, plain, 
exo поїсоп, ">, «2 plein, hir. 52 РИ ЖҮК. а, ex nolcon, “”, .. plain, 
**^, nolcon, 4%, “4, plain, «ir! ойгот ж жр]. «хе, noIcon, *^, *^, plain, 
i noIcon, me Ше plain, ge со, “o aw plain, ds noIcon, M 79 plein, 
**^, noIcon, 44, *^, plain, еке nolcon, 4% **, plain, rz», noIcon, *^, **, plain, 
exo noIcon, M" í“. plain, mE. ie E zs e. plain, VEA. noIcon, na. ше plain, 
«ж, noIcon, **, **, plain, 454! а «^^ ва plain, “x” nolcon, *", *", plein, 
**^, nolcon, **, **, plain, PME ke aw вз plain, “x” nolcon, 4”, “”, plain, 
**^, noIcon, 4, *", plain, 2 097990 i í , 
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**^, nolcon, 47, *", plein, 
B ue pn 
exo red ov es! i 
es! D PPP р а, 
, hoIcon, 4%, *^, plain, 
M n anu 
ego jb bed an и. ae 
212) nolcon, “ D ain, 
, nolcon, 4%”, “”, plain, 
“ж”, nolcon, 4”, **, plain, 
p ER 
axe dede es "P У 
exo НЕ, on ov ae j 
ғ,” ели "P es! Б 
м, noIcon, rn) p 
ex n on ..” ЖЕ 
ex» Ер, ov on a 
” ” noleon, P wv р а, 
*# го1соп, ^^, *^, plein, 
2 noIcon, oh, Ше plein, 
, hoIcon, *^, *", plein, 
о оо 
ego си "P "P du 
, nolcon, *^, “%, plain, 
"x noIcon, n ra. plain, 
авн, 
“ғ” dee жад. "P an Ri 
ex» осоп, "P e»! р o 
, nolcon, 4”, *^, plain, 
M A MN 
жу noicon, e. aa! plain, 
ex» оп, m. re вот, 
22%! no con, eer et. 405, 
eis о 20, ЕСУ жеш, 
isa! m I: eur out ded 
eee noicon, m e» piain, 
, nolcon, 47, *^, plain, 
“ж”, nolcon, *^, “”, plain, 


“=”, nolcon, 4”, *", plain, 
“22, nolcon, “”, “”, plain, 
«жи, nolcon, **, е, plain, 
ego av» we 
exo dl P av рат, 
ғ , , , plain, 
**^, nolcon, *", “# plain, 
**^, nolcon, *^, *# plain, 
**^, nolcon, **, *", plain 
); 
resource ‘SIZE’ (-1) ( 
dontSaveScreen, 
acceptSuspendResumeEvents, 
doOwnActivate, 
3932 16, 
3932 16 
); 
resource 'SIZE^ (0) ( 
dontSaveScreen, 
acceptSuspendResuneEvents, 
doOwnActivate, 
3932 16, 


3932 16 


Ф 


resource ‘ICON’ (128, purgeable) ( 
$^FFFF FFEO 8000 0030 8000 0030 EFBF FFF0" 
$^8880 0030 E8BF FFFO 8880 0030 EFBF FFFO" 
$^8000 0030 B1FF FFFE ҒҒ00 0002 В1ВА AAAA” 
$^8128 0003 BIBA AAAB 8100 0003 BIFF FFFF^ 
%”8100 0003 8100 0003 8100 0003 8100 0003" 
$8100 0003 8100 0003 8100 0003 8100 0003" 
$^"8100 0003 8100 0003 81FF FFFF 803F FFFF” 
%78000 0030 8000 0030 FFFF ҒҒҒй 7FFF FFFO" 
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Advanced Mac ing 
A Vaccine for the 'nVIR' Virus 


Unless you are going to Africa or Indochina, viruses and 
vaccinations are not something that most of us need to worry 
about. However, even if you're not planning on travelling, there 
is one virus you need to be aware of. It is a computer virus that 
isinfecting Macintoshes everywhere. [Note: The virus described 
in this article is apparently only one of at least three viruses that 
are going around as reported in the press. This article discusses 
what we shall name the 'nVIR' virus. The other two are the 
infamous ‘peace message’ virus and the ‘scrapbook’ virus re- 
ported in this month's mousehole column, and in a recent 
MacWeek article. -Ed] 


Are you infected? 

Use ResEdit to open your system file and look for *n VIR" 
resources. If you have them, then your system has been infected 
and chances are that at least some (if not most or all) of your 
applications are infected. Don't panic. This particular virus is 
relatively harmless. There is an application at the end of this 
article that will allow you to remove the virus from your infected 
applications. There is also an ‘INIT’ resource you can put in your 
System Folder that will warn you if this virus ever shows up on 
your system. [Note that this vaccine and virus warning init 
applies only to this particular 'nVIR' virus. New vaccines will be 
necessary for the other two once it is known how they operate. - 
Ed] 


How | found it 

Until last week, I had had no experience with computer 
viruses. I had heard rumors about the existence of Mac viruses, 
but didn't really believe them. I do not know when this virus first 
got into my system. It must have come from some program I 
downloaded off of a network, but I do not know which one. By 
the time I figured out what was going оп, the virus had modified 
seventeen of the applications on my hard disk and my System 
file. 


Virus Symptoms 

Sometime near the beginning of last week, I started hearing 
a beep when launching programs. It didn't happen every time, 
only once in a while and with no discernable pattern. Using 
TMON, I trapped SysBeep() and discovered that something was 
modifying ‘CODE’ 0 and installing several ‘nVIR’ resources 
into every application I launched. I looked in my System file and, 
in addition to several ‘nVIR’ resources, found an ‘INIT’ 32 
resource that I didn't put there. I compared the standard *INIT's 
from an original system disk and none of them matched the 
‘INIT’ 32 I had found. What really clued me in to the idea of a 
virus was that if I took the “ІМІТ” 32 resource out of my System 
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Virus WarningINIT 


ША!» Mike'M Scanlin 


% Contributing Editor 
MacTutor Vol. 4 No. 5 


WARN! 


Vaccination 


File: Vaccination 
Status: Resource 'nUIR' 2 not found. File 


is not infected or cannot be repaired. 


Fig. 1 Vaccination Alert tells Application status 


file, quit ResEdit, and then relaunched ResEdit, the “ІМІТ” 32 
resource would be back in there. After disassembling ‘INIT’ 32, 
I learned how it worked and how to make my system immune to 
it. I am sharing this information so that other Mac users can 
protect themselves as well. [Note that this virus exhibits the 
ability to re-install itself after being patched out with ResEdit! - 
Ed] 


How to make your System file immune 

Use ResEdit to open your System file. Create an ‘INIT’ 32 
resource that consists of these 2 hex bytes: 4E 75 (which is an 
RTS instruction). If ‘INIT’ 32 already exists and has а size of 366 
bytes, then you can be pretty sure it is the virus’ ‘INIT’. Replace 
the existing ‘INIT’ 32 with the 2 byte version (4E 75). Now create 
8 resources of the type ‘nVIR’; the case of the resource type is 
important — do not use ‘NVIR’ or ‘nvir’. Their IDs should be 0 
through 7, with size zero bytes. If they already exist, then delete 
them and create 8 new empty ones (with IDs 0-7). 

That’s it. Your system is now immune to this particular virus 
(but not all possible viruses). If you now run an infected applica- 
tion, the virus will think that it is already installed in your system 
file, since it sees the ‘INIT’ and ‘nVIR’ resources it expects, and 
will leave it alone. 

If your System file was infected before you immunized it, 
you should reboot the system before using the procedure below 
to remove the virus from your applications. This guarantees that 
the effects of ‘INIT’ 32 are removed from memory. 


Removing the virus from infected applications 
If an application has been infected, it will have several 
‘nVIR’ resources, a ‘CODE’ 256 resource, and a possibly modi- 
fied ‘CODE’ 0 resource. Here are instructions on how to restore 
an infected application (note: this is only useful if you are certain 
that your System file is not infected. Otherwise, the applications 
will become infected again. Also, you should practice on a copy 

of an infected application): 

1) Open the application with ResEdit. If ‘CODE’ 256 
exists, use GetInfo on it to check its size. If it is 372 bytes, 
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then remove it. The reason we check for the size is because 
some applications, such as ReadySetGo, already have a 
‘CODE’ 256 resource of their own and we don't want to 
remove part of the application's code. 

2) Open 'CODE' 0 and lock at the 3rd line of 8 hex bytes 
(bytes 16-23). If it is “0000 3F3C 0100 A9F0” then you 
need to replace that line of hex numbers with the 8 bytes 
contained in the ‘nVIR’ 2 resource. If the third line does not 
look like the above 8 bytes, then the *CODE' resource is 
probably protected and did not get modified — see below 
for an explanation. In this case leave it alone. 

3) Remove all ‘nVIR’ resources. Make sure you have 
completed step 2 before removing ‘nVIR’ 2. You cannot 
restore the application without it. 

Because this procedure is so automatic, I have written a 
program that does it for you. The application Vaccination dis- 
plays the SFGetFile dialog and allows you to choose an applica- 
tion to vaccinate. A message is displayed that tells you the result 
of the vaccination and the SFGetFile dialog is displayed again. If 
your system has been infected, you should vaccinate every 
application on your hard drive. You will only see files of type 
‘APPL’, *FNDR' (for the Finder), and ‘dahd’ (for the DA 
handler) in the SFGetFile dialog so you might want to do a 
manual tree walk of your hard drive to be sure you vaccinate all 
of your applications. There is no harm in vaccinating an unin- 
fected application or in vaccinating the same application more 
than once. This program does not make applications immune to 
this virus, it only removes this virus from them. But if your 
System file is immune, then there is no way this particular virus 
can spread to your applications. Note: you cannot use the Vacci- 
nation program to make your System file immune. You will have 
to do that manually using the procedure above. 


How this virus works 

This particular virus modifies the ‘CODE’ 0 resource of an 
application in such a way that when you launch that application 
the first thing to execute is a piece of virus installation code. That 
installation code looks for the virus’ presence in the System file 
you are launching from. If it does not find evidence of the virus, 
it then installs itself (as ‘INIT’ 32 and several ‘nVIR’ resources) 
into your System file and then executes the application you had 
originally launched. Once your System file is infected, every 
application launched from that system will become infected. The 
whole infection process only takes a second or two, so there is 
little chance you will notice it. If the virus detects that itis already 
in the System file and in the application you are launching 
(meaning that no installation of itself is necessary on this launch), 
then there is about a 6% chance (1 in 16) that you will hear a short 
beep. This is the beep that first got my attention. According to a 
friend of mine, Chris Borton, whose computer was also infected, 
if you have MacinTalk in your System Folder, then the virus 
speaks the words “Don't Panic" instead of beeping. 

This virus does not check if the ‘CODE’ 0 resource of the 
application it is trying to infectis protected or not. Consequently, 
applications that have ‘CODE’ 0 resources with the resProtected 
bit set are still infected, but are not contagious, i.e. they have the 
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‘CODE’ 256 resource and the ‘nVIR’ resources added to them, 
but they can not pass the virus on to a clean System file. I learned 
this by noticing that QUED/M and PageMaker were infected, but 
were not contagious. I couldn't figure out why some programs 
had protected ‘CODE’ resources and others didn't. Then one of 
the people I work with, Victor Romano, put it together. He told 
me that Lightspeed C (which QUED/M and PageMaker were 
written in) automatically sets the resProtected bit of the *CODE' 
resources it generates. MPW does not. So, protecting the 
‘CODE’ resources (which can be done with ResEdit) is another 
simple way of preventing this virus from affecting an application. 


To be forewarned 

I don't know how far this virus has already spread, or how 
far it will spread. As a partial defense, however, I have written a 
piece of code thatcan be installed as an “ІМІТ” file in your System 
Folder that will warn you if it detects something that looks like 
this particular virus. VirusWarnINIT is a patch on 2 routines that 
this virus relies on: GetResource() and ChangedResource(). The 
patch to GetResource() makes a beep if theType == ‘nVIR’. The 
patch to ChangedResource() makes a beep if theResource is a 
handle to a ‘CODE’ Oresource. I wouldn't suggest installing this 
‘INIT’ in a system known to be infected — the number of beeps 
is sure to annoy you. I would have used something like an alert 
window instead of a beep asa warning, but I can’t be sure that the 
Window Manager has been initialized at the time the virus is 
detected. If you install this ‘INIT’ in a clean system and then 
launch a contagious application, you will hear about 5 or 6 beeps 
in a row as the virus tries to install itself in your System file. 

Note that this ‘INIT’ is only a warning, not a vaccination. 
The virus will still install itself. The advantage is that you will 
know aboutitrightaway andcan stop it before it spreads very far. 

Now that my Mac has been vaccinated, it's my turn. After 
Typhoid, Yellow Fever, Cholera and Meningococcal vaccina- 
tions, I' m off to Africa and Indochina. I wonder if I can get David 
Smith to send MacTutor to Serengeti National Park? Or do they 
already get it there? ГИ let you know... 


/* Vaccination.c 
* by Mike™ Scanlin 12 March 88 
£ 
* Removes the 'nVIR^ virus from an 
* epplicetion chosen by the user. 
*/ 


*include “QuickDraw.h” 
Binclude “ResourceMgr .h” 
Binclude “StdFilePkg.h’ 
"include *FileMgr.h^ 


define NIL OL 
Sdefine гед register 


#def ine REPORT_STATUS_ALERT 129 
"define nVIRCODE_256.SIZE 372 
"define nVIR2Bad -10 
8def ine nVIR2NotFound -11 


void RemoveResourceFromFileClong theType, int theID, int 
ref Num); 
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int Innoculate(Str255 *fileName, int vRef); 
void pStrCpyCchar *p2, char *р1); 

Boolean  ChooseFileCStr255 *fn, int *vRef); 

void mainCvoid); 


static SFReply reply; 
static int app IResF ile; 


/* RemoveResourceFromFileCtheType, theID, refNum) 
x 


х This will remove the resource of type theType 

* and ID theID from the open resource file 

* whose refNum is refNum. 

x/ 

void  RemoveResourceFromF ileCtheType, theID, refNum) 
long  theType; 
int theID; 
int — refNum; 


reg Handle ` theResource; 


if ((theResource = GetResource(theType, theID)) && 
(HomeResF i leCtheResource) == refNum)) 
RmveResource( theResource?; 


/* InnoculateCfileName, vRef) 
* 


ж This removes the ‘nVIR’ virus from *fileName 
in directory vRef. 
*/ 
int InnoculeteCf ileName, vRef) 
reg Str255 *fileName, 
int vRef ; 


reg Hendle o1dCODE, currentCODE; 
reg int i, refNum, returnVel; 
ParamBlockRec рб; 


/* init the ParamBlockRec to all zeros */ 
аза ( 
Тег pb, Ad 
nove.1 sizeof (ParamBlockRec), 09 
subq.1 #1,08 


@1cir.b CA0)+ 
бга 00,61 


/% set the current working directory */ 
pb.ioParem.ioVRefNum - vRef; 
PBHSetVolC&pb, FALSE); 


refNun = OpenResF ileCf ileNome); 


if CColdCODE = GetResourceC'nVIR^, 222 6 
CHomeResF ileCo1dCODE) == refNum)) ( 
if (GetHandleSize(o1dCODE) != 8) 
/* if ‘nVIR’ 2 isn't 8 bytes, then something 
isn't right. */ 
returnVal = nVIR2Bad; 
else ( 
if CCcurrentCODE = GetResourceC'^CODE^, 05) && 
(HoneResF ileCcurrentCODE) == refNum)) ( 
asm 
MOVE.L oldCODE, А1 
MOVE.L CA1),A1 
MOVE.L currentCODE, Аб 
MOVE.L (АВ), Аб 
ADDA #16, AØ 
MOVE.L CA1)+, (А02% 
MOVE.L CA1), (АВ) 
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ChangedResource(currentCODE ); 


/* kill the ‘nVIR’ resources */ 
for Ci = 0; i <= 7; ін) 
RemoveResourceFromFileC‘nVIR’, i, refNum); 


/* kill the extra ‘CODE’ resource that this 
virus adds Conly if it has the size 
of nVIR.CODE.256. SIZE) */ 
if CCcurrentCODE = GetResourceC'CODE^, 2562) && 
(GetHandleSizeCcurrentCODE) == 
nVIR_CODE_256_SIZE) && CHomeResF ileCcurrentCODE ) 
== refNum)) 
RmveResource(currentCODE); 


returnVal = noErr; 
) 
else 
returnVal = nVIR2NotFound; 


if (refNum != epplResFile) 
CloseResF 1 leCref Num); 


return(returnVal ); 


) 

/% pStrCpyCp2, p1) 
* 
х Copy the pascal string at *p1 to *p2. 
*/ 


void pStrCpy(p2, p1) 
фы. сһаг %р2, %р1; 


reg int len; 


len = *p2** = 1р1++; 
while (-Теп ›= 0) 
*р2++ = 20144 


/* ChooseFileCfn, vRef) 
£ 
з Use SFGetFile() to get the name of ап 
* application from the user. Return the directoru 
* of the chosen file in *vRef. Return FALSE if the 
* user clicked Cancel, TRUE if theu clicked 
* Open. 
* 
* Thanks to Chris Borton for this routine. 
ы | 
Boolean ChooseFileCfn, vRef) 
Str255 *fn; 


int ] *vRef; 
SFTypeL ist nyTypes; 
static Point SFGwhere = ( 90, 82 ); 
mulupes[0] = ‘APPL’, 
mulupes[1] = 'FNDR'; 
mulupes[2] = “даһа”; 


SFGetFileCSFGwhere, NIL, ØL, 3, myTypes, ØL, &reply); 
if Creply.good) ( 

pStrCpy((char *)fn , Ccher *)reply.fName); 

жүре” = reply.vRefNum; 

returnC TRUE); 


else 
returnCFALSE); 
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void maint) ( 


Str255 fileName; 
int — vRef; 


/* save the application” resource file refNum */ 
appiResFile = CurMap; 


InitGref C&thePort); 
InitFontsC); 
InitWindows(); 

Ini tMenus( ); 
InitDialogs(@L); 
InitCursor(); 


/* keep choosing files until the user hits Cancel */ 
while (ChooseFileC&fileName, &vRef)) ( 
switch CInnoculate(&fileName, vRef)) ( 
case  nVIR2Bad: 
ParamText(&fileName, “\pResource ‘nVIR’ 2 is not 8 
bytes long. File cannot be repaired.^, NIL, NIL); 
break; 
case nVIR2NotFound: 
ParamText(&fileName, “\pResource ‘nVIR’ 2 not found. 
File is not infected or cannot be repaired.”, NIL, NIL); 
break; 
default: 
ParamText(&fileName, “\pVirus successfully removed.” 
NIL, see 


4 


/* show the result of the attempted removal */ 
AlertCREPORT_STATUS_ALERT, NIL); 


) 
шт et 
/* VirusWarnINIT.c 
* by Mike" Scenlin 13 March 88 
x 
* Put this in your system folder to warn you 
* about the ‘nVIR’ virus. 
* It patches GetResource() and ChangedResource(). 
*/ 


*include “Asm.h” 
“include “ResourceMgr .h” 


"define GetResource @хА9А@ 
#def ine ChangedResource @xA9AA 
define JMP Ox4EF9 
define X memFullErr - 108 
#def ine beepDuration 20 


void main(void); 
void main() 


asm ( 

/* beginning of the code that installs the patches */ 
поуе.1 D3,-(SP) 
/* get the original GetResource address */ 
move  fGetResource,D0 
-GetTrepAddress 

/* set up JMP instruction that calls original GetResource */ 
lea — &origGR,A1 
move  "JMP,CAD* 
поуе.1 Аб, (А1) 

/* get the original ChangedResouce address */ 
move  "ChangedResource,D0 
-GetTrapAddress 

/* set up JMP instruction that calls orig ChangedResource */ 
lea @origCR,Al 
move — "JMP,CA12* 
поуе.1 AQ,CA1) 
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/* get some space in the system heap for the patches %/ 
lea @last,Ad 
lea  efirst,A1 
Suba.141,A0 
move.] A0,D0 
299.1 5254,D0/*xtra space for Str255 (6name) */ 
move. 00,03 /* save for JBlockMove */ 


/* the length of our patches */ 


-NewPtr SYS 

cmpi 8nemFullErr,D9 

beq.s @noPatch 

move. 1 A0, -CSP) /* save for _BlockMove */ 
move. ] (SP),-(SP) /% for _SetTrapAddress %/ 


/* set GetResource to the beginning of the space we just got 
in the system heap */ 

move  "'GetResource,D0 

-SetTrapAddress 


/* set ChangedResource trap */ 
lea  @changedResouce, Аб 
lea — 8getResource,A1 
ѕира.1 А1,А0 
adda.1 (5Р2%,А0 
move  "ChaengedResource,D0 
-SetTrapAddress 


/* now move it into place */ 
lea  efirst,A0 
move.1 (SP)+, Al 
поуе.1 03,00 
-BlockMove 

@noPatch поуе.1 (SP)+,D3 

rts 


/* end of the code that installs the patches */ 
@first 


/* * This is the patch to GetResource */ 

@ge tResource 
поуе. 1 6CSP2),DO /% get theType */ 
стрі.1 ®’nVIR’, Dd 
bne.s @origGR 


/* at this point we know something is trying to load an ‘nVIR’ 
resource */ 
move  fbeepDuration,-CSP) 
-SysBeep 
/* note that this is only а warning beep, it falls through 
* to the original GetResource, so the calling function 
* never knows that it was detected. */ 
бог igGR nop /* JMP to original trap */ 


/* * This is the patch to ChangedResource*/ 
@changedResouce 
/* call GetResInfo() to see if changing а CODE Ø resource */ 
поуе.1 4(SP),-(SP) /% copy resource handle 
* that was passed to 
* ChangedResouce() */ 


pea @theID 
pea @theType 
pea @name 
-GetResInfo 


lea @theType, Аб 
move.1 (А0),00 
стрі.1 8%”С00Е”,00 
bne.s @origCR 


lea — 6theID, AQ 
tst CAB) 
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bne.s @origCR 
/* give а warning Беер а CODE 0 resource is being chenged */ 


move  *beepDuretion,-CSP) 


-SysBeep 

eor igCR nop /* JMP to original trap */ 
nop 
nop 

6theID dc 0 

@theType dc.1 0 

@name dc 0 


/* there are actually 254 more bytes to this 
ж variable (Гог а total of 256). Check the 
х 209.1 5254,00 instruction in the install code. */ 
elast 
) 


) 


* Vaccine.r Application 
ж by Mike Scanlin 
ж 


vaccine .RSRC 
77727777 


Туре VACC = STR 
0 
Vaccine for the ‘nVIR’ virus by Mike Scanlin 


Туре BNDL 
,128 (0) 

VACC 0 

ICN* 

0 128 

FREF 

0 128 


Type FREF 
,128 (0) 
APPL 


Type SIZE * GNRL 
9 
41 
00000 ;; $4000 = bit 14 cleer 
L 


128000 ;; recomended 
И 
128000 >. minimum 


Type SIZE = GNRL 
241 


| 

00000 ;; $4000 = bit 14 clear 
L 

128000 ;; recomended 

.L 

128000 ;; minimum 


Туре ALRT 
,129 (0) 

80 64 188 448 

129 

4444 


Type DITL 
‚129 (0) 
3 


Button 


78 20 98 80 
OK 
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IconItem Disabled 
10 32 42 64 
0 


staticText Disabled 
10 110 112 374 
File: 70 \00++ 
Status: ^1 


Type ICN® = GNRL 
,128 (0) 
H 


2000 0000 4000 0000 A800 0000 1400 0000 
2200 0000 1100 0000 0880 0000 0440 0000 
0220 0000 0120 0000 00Е0 0000 0010 0000 
0008 0000 0000 0000 0007 FFCO 0008 0020 
0009 FF20 000A 00А0 000А 44А0 000А BOAO 
000А 38A0 000A 44A0 000А 00А0 0009 ҒҒ20 
0008 0020 0008 0020 0009 0-20 0008 0020 
0008 0020 000А AAAG 0008 0020 000Ғ FFE 
2000 0000 4000 0000 А800 0000 1С00 0000 
3E00 0000 1Ғ00 0000 0Ғ80 0000 07С0 0000 
03Е0 0000 01-0 0000 00-0 0000 0010 0000 
0008 0000 0000 0000 0007 FFCO 000Ғ FFEO 
000Ғ FFEO 000Ғ FFEO 000Ғ FFEO OOF FFEO 
000Ғ FFEO 000Ғ FFEO 000Ғ FFEO 000Ғ FFEO 
000Ғ ҒҒЕй 000Ғ FFEO 000Ғ FFEO 000Ғ FFEO 
000Ғ FFE® 000Ғ ҒҒЕй 000Ғ FFEO 000Ғ FFEO 


ж VacInit.r INIT resources 

* for detecting 'nVIR^ virus 
* by Mike Scanlin 

x 


VacInit .RSRC 
22227777 


Type VNIT = STR 
0 
Virus detection init by Mike Scanlin 


Type BNDL 
,128 (0) 

ҮМІТ 0 

ICN* 

0 128 

FREF 

0 128 


Type FREF 
,128 (0) 
INIT 0 


Туре ICN® = GNRL 
,128 (0) 
H 


2015 724E 4015 4450 A815 4А50 1415 7246 
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Advanced Mac'ing 


Protocols for an IAC Driver, Part 1 


How to Get Your Applications 
Talking to Each Other Again 

The meeting had just broken up, Paul and I were at the local 
beer-and-beef joint, and we were feeling rather annoyed. We had 
been told that Apple wasn't going to be implementing any sort of 
method for really using MultiFinder to the max until at least 
System 7. No form of inter-application communications until at 
least then, they said. 

"Can't really be all that difficult," I said over a cookie milk 
shake. “Рог Pete's sake, you could use a device driver to get the 
needed “alien” memory needed for communicating! Drivers 
normally have to grab some working memory when they open 
anyway, so it's no big deal." 

"Of course it's not that hard! You and I could probably do 
a complete job—with sample applications to show Dave Smith 
that we're not circling in a low orbit — іп a few evenings,” Paul 
rumbled back over his cookie shake (they make awfully good 
shakes there...). “Іп fact, we oughta do just that! Show Apple all 
the talent isn't inside the city limits of Cupertino..." 

Thus was bom the SAWS Inter-Application-Communica- 
tions Protocol (detailed in the accompanying description of the 
protocol). Our purpose in writing it was to show that communi- 
cating between programs under MultiFinder isn't really that 
difficult in principle (a proof by demonstration) and have some 
fun in the process. In the next few months we will be publishing 
the device driver, its installation INIT, and a variety of samples. 
Various other members of the Chicago-area Mac Gang are 
joining in on the fun by writing and submitting simple applica- 
tions such as graphing programs, text editors, etc. that commu- 
nicate between each other using the IAC protocols. 


While the protocol is copyrighted, 
anybody may use it freely. 

We hope that encouraging its widespread use will help 
spread the concept of mix-and-match software in the community 
and let people discover how nice really personalized, *custom- 
blended" software is. Widespread experimentation in the free- 
ware/shareware arena may also help usall find out what interface 
approaches work and what approaches don't. 

Assumptions: I made the following assumptions about my 
users in designing the protocol: 

1) Programsmustexplicitly be written to use this protocol. 
It is NOT written to be retro-fitted onto existing applica- 
tions. Many developers grumble about MultiFinder and the 
numerous kludges it contains in order to be compatible with 
existing programs; the fact is, however, that MF is a 
triumph of programming precisely because it succeeds in 
that compatibility with programs written when it didn't 
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exist. I am not convinced that a backwards-compatible 
approach is even possible. 

2) They are using several programs together on a single 
machine, rather than across a network. This simplifies 
communications greatly. 

3) Documents will tend to be used together on the same 
machine, most often the machine where they were created. 
This reduces the probability of “collisions” between docu- 
ments created on different machines but being processed 
together. We can thus use a simpler method of identifying 
documents so that they can “recognize” each other. 

4) Enough information must be stored with documents to 
allow links to be reestablished as automatically as possible 
when stored documents are reopened. 

5) The user interface should seem to be a natural extension 
of the existing interface, needing minimal learning and not 
intruding into the normal operation of the programs using 
it. Larry Atkin at Odesta suggested presenting it as an 
extended clipboard, hence our “magic clipboard” meta- 
phor. 

Basic Concepts: Given 2 programs running together under 
MultiFinder, they are linked if changing a specified chunk of data 
in document ‘A’ (the source) results in the changed data being 
used in document ‘B’ (the target) without any explicit interven- 
tion by the user. We say that the target document is dependent on 
the source document. This idea is central to our entire design. 

Notice that while we assumed 2 programs running under 
MultiFinder, we spoke of documents being dependent on each 
other. This is due to the ability of most programs to manage 
multiple documents; the programs carry out the communication, 
but the documents are related. 

There are two mechanisms needed for programs to be able 
to communicate automatically under MultiFinder (or any multi- 
tasking system, for that matter): 

1) Amethod for a“ target” program to determine that a chunk 
of data it is interested in has changed, so that it can retrieve 
that data. 

2) A method of transmitting chunks of data between pro- 

s. 

Our protocol addresses both of those problems in a simple 
fashion. Let me emphasize that there are many ways of address- 
ing them—the designer's choice of methods depends on the 
needs of her/his users. Apple's final approach will probably be 
quite different from ours (but who knows)? 

Keeping track of changed data: This is the feature of the 
IAC protocol that allows data to flow between programs without 
user intervention. Since there are 3 parties involved with the 
process of getting data between programs (source, driver, and 
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target), 

there are 3 places where knowledge of the relationship between 
programs can be kept. Having the IAC driver keep track of which 
target documents are interested in a given chunk of data (called 
an "extent" in the protocol description) is the simplest solution: 

1) Source programs simply publish the latest version of an 
extent when it has changed. They have no knowledge of 
who's interested, thus keeping their lives simpler. 

2) A target program can retrieve data from a number of 
source programs with calls to just the IAC driver, rather 
than having to have some way of communicating with each 
source program explicitly. 

Since an extent of changed data must be stored by the IAC 
driver anyway, we have added a feature to deal with the possibil- 
ity of data being updated before all target documents have 
retrieved it. This is called an "edition," and starts with 1 when 
data is first written to the driver. If a new edition of an extent is 
written to the driver before all target documents have retrieved an 


existing version, the latest edition is linked at the end of a chain. 
Target documents, by convention, remember the last edition read 
and simply request the latest edition higher than that. 

When a document makes a data extent available to other 
programs for the first time, it is issued a document ID by the IAC 
driver, which serves as part of an "address" in communicating 
later. A properly written IAC application will store the document 
ID for each extent itis a target of so that (in а later session) should 
that document be opened the links can be automatically re- 
established. 

Communicating between programs: The IAC driver 
serves in some respects as a set of highly intelligent clipboards, 
or mailboxes. А source program actually writes a chunk of 
changed data to the driver, using normal write calls to the file 
system, where it is stored until all the target programs that are 
interested in that chunk have read it, using normal read calls to the 
file system. While temporarily storing the data in the driver does 
take space, our only alternative would be to manipulate the data 
in different application heaps. This would require too much 
knowledge about the unpublished guts of MultiFinder to be 
either stable or safe. 

A major implication of using normal file system calls for 
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communicating is that target programs must actively poll the 
IAC driver in order to determine if the data they need has 
changed. This can be done both in the foreground and the 
background. However, if the target application genuinely needs 
to ignore the outside world for a while, there is no penalty since 
succeeding editions of each data extent are maintained by the 
driver. 

Since our driver has functions significantly different from 
those of a standard driver, it needs a different set of parameters. 
These are transmitted in the I/O buffer that is used in read & write 
calls; since control calls to drivers don't use a buffer, control calls 
aren't used. 

Interfacing to theIAC driver: While the attached protocol 
description gives the details of how the driver works and how to 
work with it, there is no need for everybody to re-invent the 
interface. Therefore, in the sample test program that will accom- 
pany the actual driver, a set of interfaces in C is provided as a 
package that can be used “off the shelf.” The interfaces deal with 
the messy details of setting up parameter blocks, doing the calls, 
and checking operation statuses. Since most of the intelligence 
resides in the driver, they are straightforward. 

Without further ado, here is the definition of the protocol and 
its associated routines: 


A Protocol for Inter-Application Communications 
Under MultiFinder 
— Version 1.2 — 
© by Frank Alviani and Paul Snively, June 1988 
Permission granted to MacTutor for Publication 
АП Rights Reserved 


This document is intended to define how programs may be 
written to support “hot links" between several programs execut- 
ing en suite under MultiFinder, using a device driver to provide 
the communications facilities required. It is divided into the 
following sections: 

1) Definition of the concepts implemented. In particular, “hot 
links" and “data dependency" are defined. 

2) Definition of the facilities made available by the device 
driver, and how they are used by the "TAC-friendly" pro- 
gram. 

3) Operation of the driver and its internal data structures. 

4) Suggestions for user-interface implications of this proto- 
col, and how they might be implemented. 

5) A list of the data formats supported in this version. 

It is our hope that these protocols will be adapted freely and 
further improve the power and sheer fun of the Macintosh 
interface. 


Section 1—Definitions and Assumptions 

е An “extent” is the amount of data involved in a “data 
dependency". The source program must maintain the start 
and end of the extent in order to be able to detect when it has 
changed, so a change notice can be posted to all interested 
programs. 

* A “data dependency" exists between a "source" document 
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anda "target" document when achange in an extent manipu- 
lated by the source program requires the data manipulated by 
the target program to change to correspond. In this protocol, 
the source program uses the device driver to make the 
changed data available to all interested target programs, and 
to post notification that the change has occurred. Target 
programs, in this protocol, are required to periodically poll 
the device driverto determine the latest state of the "foreign" 
data they are interested in. 


It is vital to note that the basic objects dealt with are links 
between documents. This is required because most well-de- 
signed programs can manipulate several documents simultane- 
ously. However, we often refer to source and target programs, 
since those are the machinery behind those documents; this is 
done when we are dealing with actually reading and writing the 
changing data. 

Data dependencies involve several components. The com- 
plete set of data required must include: 

1) The data itself, referred to as an extent.. The source 
program must maintain some way to remember its range - 
a block of cells in a spreadsheet, or a selection in a text 
document - so that it can be communicated after a change 
has occurred. 

2)  Whenadependencyisestablished by a source program, 
the IAC driver must have a way of identifying it later. This 
identification is in 2 parts: 

A) It issues a document ID. This is the clock time in 
seconds, assigned by the IAC driver when a dependency 
is first registered. We work under the assumption that it 
is impossible to complete all the actions required to 
establish and complete a dependency in less than 1 
second and register a second dependency. Just in case 
someone is using Tempo, the driver can maintain a 
record of the last document ID issued and if the next one 
would be redundant, add 1 to maintain uniqueness. 

B) It issues a "hatcheck" for the extent - an index of the 
extents registered so far for that document. Extents are 
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always identified by the combination of document ID 
and hatchecks, by both source and target programs. 
Hatchecks are unique and associated with a specific 
extent and document. 

3) The identity of all target documents. А data source can 
be linked to up to n other documents. As a part of the 
updating process itis necessary to have some way for target 
programs to indicate that they've gotten the newest version 
of the data. The *slot ID" is used for this purpose; it is an 
index into the IAC driver's internal table of registered 
documents. 

4) — Ап“едшоп” indicator for the data. When apiece of data 
is linked to a target document, it is given level 0; the 1st 
change results in level 1, etc. When several links exist 
between a source and a target document, the edition asso- 
ciated with each extentallowsthe target program to identify 
and "grab" just the data units it requires to be “ир to date." 
When an existing document is opened all existing extents 
are assigned edition 0 to keep the bookkeeping manage- 
able. 

5) А format indicator. This serves the same purpose as it 
does for the clipboard. If a target program is unable to 
interpretany of the formats provided by the source program 
the dependency cannot be established and the user must be 
informed. 

° А “hot link” is the user-interface for these data dependen- 
cies. It is the visual means of: 

a) Specifying the range of source data to be echoed from the 
Source program to the target program. 

b) Indicating the location in the target document where the 
source data is to be included and shown. 

° "External link definition" is the information stored in both 
the source and target documents that allows the data de- 
pendency to be re-established after they have been closed 
and re-opened and are being manipulated together. 


Assumptions: The design laid out in this document is based 


on the following assumptions: 


1)  Thisis aimed primarily at individual users, or people 
working in small groups; this provides a simpler environ- 
ment to plan for. In particular, this allows the use of fairly 
simple external link information. 

2) Manual intervention by the user at any point should be - 
absolutely minimal and transparent. 

3) There is no need for "system administration" opera- 
tions, and therefore are no provisions for them. 

4) Programs need to be written to be “ТАС” friendly; this 
is not a facility designed to be retrofitted to existing works. 


Section 2 - Device Driver Facilities and their 
Usage 
À)  Thedevicedriver will beopened by an INIT31 resource 
at boot-up. It will remain open at all times. It will be named 
“ЛАС.” User programs gain access to it by opening it 
(which is harmless) in order to get an ioRefNum for further 
access. While we are less than thrilled at forcing the user 
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programs to open a driver with a specific and fixed name (it 
seems to be a rather "brittle" approach) there doesn't seem 
to be a better way. 

B)  Sincethe normal device driver calls do not have provi- 
sions for extensions to the standard parameter blocks, the 
necessary additional information will be passed at the 
beginning of the buffers thatare part of the driver calls. That 
is, the buffers will consist of ап “ТАС parameter block" 
followed by one or more data blocks. 

C) The basic operations supported by the driver are the 
following: 

]) Establish Dependency. This is a 2-part process that 
involves both the source and the target programs. After the 
user has determined the data of interest, the source program 
tells the driver to “add this extent to the dependencies 
table," at which time it becomes the "available depend- 
ency." After the user has determined where the source 
extent is to be linked into the target document, the target 
program tells the driver "I am interested in the available 
dependency." Note that a benefit of the above approach is 
that several target programs can each indicate they are 
interested in the same source extent without having to re- 
establish it each time. A variation of this occurs when an 
open target document determines that it can re-establish an 
existing link with a source program, in which case the target 
program will specify the document and extent it is inter- 
ested in. 

2) Remove Dependency. This сап be done by either the 
source or the target program. Target programs normally 
sever their dependencies when closing a document. If all 
target programs sever a dependency, the source program is 
notified so it can avoid the overhead of posting future 
changes; this notification occurs in the ioResult field of the 
next “UpdateData” or “Check status” calls. 

3) Identify a dependency as the “available depend- 
ency.” This is implemented to simplify the process of 
linking more than one target to a single source extent. 

4) Census. This can be called to get a list of all registered 
extents, so that programs can determine if external links 
have changed. It would normally be called if the latest 
“check status” call showed that the number of registered 
documents had changed since the previous status call. 

5) Check status. This call is normally made by all 
programs during their “null event” processing, in order to 
determine what can be done. If several links are being 
maintained, this can save the effort of making a “Read- 
Data” call for each extent. The user program should be very 
careful to make any needed calls in response to the IAC 
status before using any of the event-manager calls that 
could result in your program being swapped out; this will 
ensure the consistency of the environment. 

6) Update data. The source program “writes” an extent to 
the IAC driver (identifying the extent, of course). The 
driver will assign it the next edition for that extent. It will 
be placed into a queue if any previous editions for that 
extent remain “unvisited” by any interested target pro- 
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grams. 

7T) Read Data. This is of the form “I am interested in extent 
‘x.’ If it is more recent than edition ‘y’ please give me the 
new data.” If the indicated extent is not newer 0 bytes of 
data will be returned. 

D)  Itisimportanttonote that the source program must copy 
the extent to the IAC driver, and the target program must 
copy it from the driver. This approach was chosen deliber- 
ately, in spite of the seeming overhead, for the following 
reasons: 

1) It avoids the potentially severe memory-management 
problemsassociated with multiple heap-zones. Frankly, we 
don't know all the possible evil ramifications of trying to 
resizearelocatable block in another zone (forexample) and 
don't care to find out the hard way. 

2) The target document is guaranteed to have data avail- 
able at all times, even when it is re-opened without the 
source document. Having a graph vanish from a text 
document because you forgot to open the spreadsheet the 
graphing program was dependent upon would be justly 
perceived as a Bad Thing. 

E) Thedriver will not permit dependencies to be defined in 
the following situations: 

1) In both directions between 1 extent in each of 2 docu- 
ments. This is to avoid an infinite-loop of updates. 
2) Within the same document. 


External Link Information: This is crucial in allowing 
documents to re-establish links after they have been closed and 
are being reopened, without manual intervention. The basic 
principal is that programs must retain identifying information 
with documents that allows a “target” document to recognize its 
*source" documents; this information is given to the IAC driver 
when extents are first registered. | 

While the document, ID/hatCheck combination is not per- 
fect (primarily in a larger environment where several documents 
could be initially registered simultaneously to within 1 second), 
it seems workable as the external link information and has the 
virtue of simplicity. While "collisions" are possible, we assume 
related documents would be exchanged together and therefore 
processed together, maintaining the original context. 

The syntax of the IAC driver calls: These will be described 
in terms of the “standard” calls made to the device driver and the 
fields in the parameter block that starts the I/O buffer. All calls 
return a value in the ioResult field of the standard parameter 
block, which should be checked by the user program. Since the 
control message to I/O drivers makes no provisions for buffers, 
we need to use just the read/write calls. 

In the parameter blocks below, links are identified by both 
“slot_ID” (for the program) and “hatCheck” (for the document/ 
link). While the use of 2 fields may seem slightly redundant, it 
seems easiest to work this way, since there are occasions when 


we need identification of just the program. 
1) AddDependency: via FSWriteC) 
block: short func = 1; 
long docID; 


/* IN */ 
/* IN/OUT */ 
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short Slot. ID; /* OUT */ 
short . hatCheck; /* IN/OUT */ 


short edition; /* OUT */ 


docID is needed to identify the source document. If docID 
is zero, the source program has never registered this document 
with the IAC driver before; the assigned docID will be returned. 
docID should be stored with the document. As it identifies when 
the dependency is first registered (in seconds), it is extremely 
likely to be unique. docID should be 0 only for the first extent 
being registered for a document; all succeeding extents must 
have a valid docID value in order to be associated with the correct 
document. 

slot ID identifies the document during the course of the 
current session. It will be assigned by the IAC driver if O (zero) 
on input. If itis known (because the document is the target for 1 
or more dependencies) it should be filled in to keep the internal 
tables of the IAC driver consistent. 

hatCheck is the opaque identifier assigned to this extent. If 
this field is 0 (zero) on input, a value will be assigned by the ТАС 
driver. When a valid docID and hatCheck are provided the driver 
assumes an existing extent is being registered by the source 
program. It must be used in all future communications regarding 
it, by all programs interested in it, both source and target(s). 

edition will be returned as O (zero) in this version. 


It will be necessary to use the “WriteData” call after the 


dependency is started to actually post the data to the driver. 
2) ConpleteDependency: via FSWriteC) 
block: short func = 2; /* IN */ 
long docID; /* IN/OUT */ 
short — slot ID; /* IN/OUT */ 
short — hatCheck; /% IN/OUT */ 


docID is used to identify the source document. If itis 0 (zero) 
on input the ТАС driver will assume the “available dependency" 
(this is a "defaulted" call); the hatCheck field will be ignored in 
that case. If it is non-zero both docID and hatCheck must match 
a registered extent. 

slot. ID is used by the IAC driver to know what documents 
are targets for a dependency in order to maintain the "interest 
mask" (described below). The source document for the depend- 
ency, however, does not need to know and is never informed of 
the targets. As explained above, it should be filled in if known; 
if 0 (zero) the value will be assigned by the driver and must be 
provided in all future calls . 

hatCheck is returned to identify the extent involved in the 
dependency (it is identical to the identifier issued by AddDepen- 
dency to the source program), and must be used in all future 
communications with the driver. 

The "ReadData" call must be made to actually retrieve the 
data for the newly established link. 


3) RemoveDependency: via FSWriteO 
block: short func - 3; /* IN */ 
long docID; /* IN */ 
short slot ID; /* IN */ 
short hatCheck ; /* IN */ 
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docID and hatCheck are used to identify the extent and 
source document involved. 

slot ID is used to identify who is terminating their interest 
in the dependency. 

If the source program is involved, the data for all editions of 
the extent are immediately purged. The edition will be set to -1 
so that all interested target programs will be informed the next 
time they execute а "Status" or "ReadData" call. As target 
programs attempt to retrieve the latest version of the data they 
will be informed that the source has terminated the dependency, 
and the target's bit will be turned off in the interest mask in the 
extent entry. When no interested targets remain, the extent entry 
is purged. If, instead, all target programs terminate their depend- 
ency on an extent, the source program is informed so that it can 
stop tracking changes in that extent. 


4) AvailableDependency: via FSWriteC) 
block: short func - 4; /* IN */ 
long docID; /* IN */ 
short hatCheck ; /* IN */ 


This sets the indicated extent as the "available dependency" 
that will be the source to future defaulted “CompleteDepen- 
dency” calls. 


5) Status: via FSRead() 
block: short func = 5; /* IN */ 
short slot. ID; /* IN */ 
short — vers ID; /* OUT - driver version */ 
short  doc.count; /% OUT - * active */ 
short — extent count; /* OUT - relevant */ 


slot. ID is passed in to identify the document that is making 
the inquiry. 

vers ID is always returned. It is an integer with an implicit 
scaling of 100; i.e. version 1.0 is returned as 100, version 1.01 as 
101, etc. 

doc count is the number of documents currently registered. 

extent count is the number of extents relevant to the docu- 
ment. 


6) Census: via FSReadC) 


block: short func = 6; /* IN */ 
short X extent count; /* OUT */ 
/* for each extent: */ 
long docID; /* OUT */ 
short hatCheck; /* OUT */ 


extent. count is the total number of entries in the census. 
each censusentry consists of the current values for the docID 
and hatCheck fields. 


T) WriteData: via FSWriteC) 


block: short Гипс = 7; /* IN */ 
long  docID; /* IN */ 
short  hatCheck; /* IN */ 
short edition; /* OUT */ 


short format count; /* IN - 8 of formats */ 
handle the. data; /* IN - hendle to dete */ 
/* In the block whose handle is pessed, the following 
* is repeated once per format supported by the user 
* progrem 
*/ 
short format code;  /* format of this data */ 
long  deta size; /* size of this data */ 
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Аы the actual data .... 

docID and hatCheck identifies the extent to be updated. 

edition is returned for the use of the user program. It is 
optional whether it is retained with the document, but may be 
useful somehow. 

format count is the number of copies of the data that are 
being written in this updating of the extent. It can vary from 
update to update. For each copy of the data included in the block 
whose handle is passed in the buffer you must precede the data 
with: 

format. code, as shown in the list later in this document. 

data size must be rounded up to an even number of bytes. 


Now comes the actual data. 
8) ReadData: via FSReadC) 

block: short func = 8; /* IN */ 
long docID; ИІН */ 
short 5104 ID; /* IN */ 
short hatCheck; /* IN */ 
short edition; /* IN-OUT */ 
short format. pref(3];  /* IN */ 

/* this is an array of preferred formats */ 
short format. code; /* OUT */ 
handle (һе data; /* IN */ 


docID and hatCheck specifies the extent and source docu- 
ment. 

slot ID specifies the target document that is interested in it. 
edition is set by the user to the minimum change-level he is 
interested in (normally 1 more than the last edition it accessed); 
on output it contains the actual edition returned. The driver can 
(and probably will) skip any intervening editions, and mark them 
as “read.” The user program should remember this value, but it 
need not be preserved when the program quits, since all extents 
start at level 0 when an existing document is opened. 

format. pref is an array that specifies up to 3 data formats the 
user program can accept, in order of desirability. А null entry 
ends the list if there are less than 3 entries. 

format, code will specify the actual format returned. 

the data is a handle to a block in which the data will be 
placed. It can be allocated to 0 bytes since the driver will resize 
the block as needed. 


Section 3 - Operation of the IAC driver 
е The driver will maintain a list of all currently-registered 
documents. This is a dynamic list. A fixed array of n 
(numbered 0 to n-1) entries is maintained. When a docu- 
ment terminates, it's slot is made available — the array is not 
compacted. The slot index is also the bit index in the “who's 
interested" word maintained with each extent. 

When an extent is registered or linked to an additional 
document, the bits for each interested target document are turned 
on in the “interest mask". A copy of this is issued to each change- 
level when it is accepted by the driver. Asa target program copies 
that change-level, its bit is turned off in the mask; when the mask 
hits 0, all interested parties have accessed it and it is discarded. 

• The entry for an extent (not an edition!) is structured as 


follows: 


handle next extent; /* link */ 
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1) 


2) 


3) 


4) 


3) 


long document. ID; 

short hatCheck ; 

long naster interest mask; 
handle — head. of edition. list; 


е The entry for an edition is structured as follows: 


handle link_to_next_CL ; 
long interest mask; 
short number f ormats stored; 
struct ( /* 1 entry/format */ 
short format.code; 
handle data. handle; 


); 
The process of determining the dependencies that are of 
interest to a given document (in response to a Check status 
call) is quite simple. The slot ID of the inquirer specifies 
the bit to check in the interest mask for each active extent/ 
edition, so it involves merely scanning every active extent/ 
edition and remembering which ones have that bit set. 


Section 4 - User Interface Suggestions 

The most natural metaphor for the user is that of the 
*magic clipboard" that handles all the details of cutting and 
pasting for him/her automatically. In line with this meta- 
phor, the establish-dependency item on the Edit Menu 
could well be called “Hot Copy," with the complete- 
dependency item called “Hot Paste." (Thanks to Larry 
Atkin for the suggested names.) 

There should be a mechanism for identifying (display- 
ing) active dependencies in a document. This can be imple- 
mented by some alternative highlighting of the extent, for 
example. 

Clicking (double-clicking?) опа displayed dependency 
should cause the program (if it is the source program) to 
send a message to the IAC driver identifying that extent as 
the “available dependency” so it can be simply linked to a 
target document. This approach avoids problems associ- 
ated with trying to link the same source extent to several 
documents (such as accidentally changing the range of data 
involved for different links). It may be desirable to have 
some slightly different highlighting (such as a darker 
stipple) in order to identify the “available dependency." 

Itis usually (but not always) desirable to post an update 
for an extent only when the changes are done and the data 
will be stable for a reasonable amount of time. In a text 
selection, for example, this means that you shouldn't post 
a data change for every character typed, but wait until the 
insertion point is placed outside the data range. There are 
times when every single change—no matter how small— 
should be posted immediately, so this is a somewhat elastic 
guideline. 

In data structures that can be expanded & contracted 
(such as a text selection) the definition of the extent should 
be modified as needed as changes are made. In a text 
selection, for example, if some characters were inserted 
into the middle the original starting and ending characters 
would still be the start and end. 


Section 5 - Data Formats Supported 
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3) РСТ. Probably should include PICT2. 


1) Plain text. 4) Spreadsheet range. 
2) Formatted text (a TE scrap record with style informa- 
tion). This is what we have designed. It will probably take some 


time for these concepts to soak in, which is just as well, since the 
driver (as of this writing) is still in the process of being imple- 
mented. Next month we will publish the commented MPW 
assembler source code of the driver, along with support stuff (like 
Rez source for its resources, an accompanying article, etc.) and 
our first sample application that supports the driver. Hopefully ` 
this has whetted your appetite somewhat, and, like us you can't 
wait to see a spreadsheet, graph program, and word processor, all 
running under MultiFinder, and to make a change to the spread- 
sheet, which then causes achange in the graph, which then causes 
a change in the report in the word processor. Until then, try to 
absorb this hodge-podge of information that Frank has put 


otipple-Highlighted together and I have tried (ahem) to clarify and verify in terms of 
text-document accuracy. Happy hacking! см! 
link PEEPS 
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Advanced Mac ing 
ТАС Driver, Part II 


MacPaint 


Inter-Application Communication Under MutiFinder: 
The Continuing Saga, 

or 

Data, Data, Who's Got the Data? 
or 

If One Application is the Master 

and the Other is the Slave, 
is the IAC Driver a Slave Driver? 


Greetings, ladies and gentlemen, and welcome to yet an- 
other episode in the latest Macintosh development soap opera. In 
this segment, we ask the crucial question, “What does it actually 
take to make this puppy fly?" Luckily, Frank has spent a great 
deal of time and effort answering that question to his own 
satisfaction while I was out dancing with Shellie and Alice in 
Boston. (We should all be so lucky, I might add.) 

Seriously, here is our attempt at cleaning up some of the 
mysteries surrounding how this driver we've written actually 
works. The definitive answer to that whole question can, of 
course, only be ascertained by careful examination of the source 
code, a herculean task at best. 

Rather than put you, gentle reader, through that, here is our 
distillation of both what we wrote last month, and what is in the 
source code that accompanies this article (which is supposed to 
be reasonably short, since the code is far larger than anything 
MacTutor has ever published before). 

_ Disclaimer!! This version of the ТАС Driver is 81!! We 
have had enough requests and inquiries to convince us to go 
ahead and release this early Beta version for people to experiment 
with, understanding thatrevisions are inevitable. THIS DRIVER 
UNDOUBTEDLY STILL HAS A FEW BUGS IN IT! Don't 
commit all your eggs to the IAC basket just yet!! 

Firstofall,the driver had to be remarkably transparent (read: 
drop it in your System Folder and forget that it exists). For that 
reason it is a Startup Document (for you pre-System 6.0 freaks, 
it's an INIT file). Basically there's a ridiculously simple little 
INIT in there that opens the DRVR in the system heap, makes 
sure it's in the unit table, and then makes sure that it won't go 
away when the INIT file is closed (by detaching the resource). 
Peter Helme of Mac DTS kindly provided a small chunk of code 
that finds the highest unoccupied slot in the unit table and 
renumbers the DRVR resource to ensure it is loaded there. 

Once the driver is there, applications are free to check to see 
if it's around and, if it is, to make use of it. The calls were 
documented last time as to name and function (sort of), so I'm 
going to try to focus on some of the not-so-obvious aspects of 
what goes on, and why (Frank is actually explaining the "why"; 
it's his design, after all). 
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First of all, understand one important fact: inter-application 
communication under MultiFinder (or any other multitasking 
environment, for that matter) is neither more nor less than an 
exercise in memory management. The source application has to 
allocate storage for the transfer of data to the target application, 
and somehow the target application has to be made aware that the 
block of memory has something that it wants. Also, since the 
source data can be changed in a fairly dynamic manner relative 
to the target retrieving the data, you have to keep track of various 
versions or “editions” of the data somehow. All of this is the 
driver's responsibility. It allocates and releases the storage (yes, 
Paul Sydney, it “does” release the storage), and it tracks editions 
as necessary. 

А second matter to consider during program design is that 
inter-application communication is very much like network 
communication (only without the messy wires) and therefore 
similar problems arise, such as timing and coordination difficul- 
ties. If you've never dealt with those before, it's going to prove 
very stressful for a while (although the problems aren't really of 
the same magnitude). 


Specification changes 

Since the time the protocol was published in the August 1988 
issue of MacTutor, a few small changes were found to be 
necessary in the specifications. Here they are: 

1) The identifier for data types was changed from a 16-bit 
integer to the 4-character resource type used by everybody else 
(no, I don't recall the good reason I had for choosing an integer 
in the first place). 

2) The information returned by the Census call for an extent 
now includes the latest edition, since that is necessary for the 
application to be able to determine if it needs to read that extent 
or not. 

3) When an extent is deleted by its source, the entry is 
removed from the table entirely (rather than just setting the 
edition to -1 as originally stated). Targets that try to access that 
extent in the future will get a “М о such extent" error from the 
driver, and will know to not try to read it anymore (the extent 
should NOT be purged from the application's internal tables, 
since re-opening the document in the future will re-establish the 
dependency). 


Internal Data Structures 
One of the keys to understanding any piece of code is a good 
grasp of the data structures it uses: how they are used and why 
they were chosen. The data structures used in the IAC driver are 
not terribly complex. 
Theextenttable - is the heart of the driver. Itisa fixed-length 
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table that includes information about where an extent originates, 
who is interested in it, and what is the latest version of data that 
each target has read. 


NN 
Ix 


Since the entry for an extent is a fixed size structure, the 
entries for each edition are kept ina linked list. Editions are added 
to the list in chronological order, with the newest edition closest 
to the extent entry. Each edition in turn is a variable-size structure 
(the size of an extent's data can of course vary, and the number 
of formats written to the driver can vary for each edition) and is 
therefore also a linked list. The data format identifier for each 
chunk of data is stored in the block with the data as a 32-bit 
header. 

Ihe interest mask — is used to identify targets for a source 
extent. The position in the document-ID table serves as a bit 
number in this mask (i.e. slot 2 is bit2 in the mask). In theextent's 
entry in the master table, the bits serve as identifiers of the target 
documents, and are only turned off by atarget document severing 
a link. In the mask stored with each edition, the bits serve to 
record which documents have not yet read the data, and are 
turned off as soon as atarget has read an edition. The read routine 
checks the interest mask for an edition after returning the data, 
and deletes the edition if no interested targets remain. 

The document-ID table - is a table of unique document IDs. 
Every entry in this table is one of three types - Empty (zero), 
Target Document (1), or Source Document (a negative number). 
It is critical for every document interacting with the IAC driver 
to appear in this table, since the slot ID is used to access the 
interest mask for extent entries; yet, document IDs are only 
assigned to source documents (a document that is only a target of 
others does not need to be identified by other than its slot, ID) - 
how to resolve this? 

Target-only documents are those that do not pass a docu- 
ment ID to the "Complete Dependency" call; a dummy entry is 
put into the table to uniquely identify them for this session, and 
а slot ID is assigned. Later, if they make an “Add Dependency" 
call and pass the existing slot. ID in (as they must under the 
protocol), the slot. ID is used to put the new document ID in the 
table, replacing the dummy entry. We take advantage of the fact 
that all date/times returned by the system are negative numbers 
to make this easy to process. 

These data structures were designed for simplicity; they 
contain the minimum amount of information that will allow the 
driver to do its job. They do not, for example, maintain any 
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Master Interest Mask 
Edition 
Hatcheck 


Document ID 


31 30 29 2 1 O 
1 
2 
3 


31 
32 


Slot IDs are non-zero and address thebits Modulo-32. 
This is automatic when using the bit instructions of the 68000. 


information about the "boundaries" of extents, since that is 
highly application specific and impossible to anticipate; also, 
maintaining that material in the driver would result in excessive 
traffic between the IAC driver and applications. 


A Routine Commentary 

Most of the stuff from last time that concentrated on the 
interface specifications was explained fairly well, and I don't 
wish to copy it here. Instead, I will provide my commentary on 
things that were perhaps not that clear. I'll go routine by routine. 

Open - itturns out to be impossible to check for MultiFinder 
at boot time, when this driver is opened. Therefore, it is the 
responsibility of the application to check and refuse to try and 
support IAC operations when MultiFinder isn't running. The “С” 
glue code provided does this check during the open call, so you 
shouldn't need to. 

AddDependency —What's hard about this? Not much! 
Basically what it does is to add anew entry to the driver's internal 
tables that are used to keep track of data that is being made 
available to interested applications. This is called by the source 
application. 

Thereare 2 waysin which a source application can make this 
call: with a default document ID of zero, or with existing 
document and slot IDs (the driver has no way of checking up on 
you, and assumes that non-zero IDs are valid). The default case 
is easy - just give the document it's IDs and send it home. If IDs 
are provided, however, life becomes complicated - there is the 
possibility of collisions with slot IDs already registered. If that 
occurs, a new slot ID is assigned and returned to the caller — this 
is why theslot ID returned from this call MUST ALWAYS be the 
one used in further communications with the driver. 

A reminder that this call does NOT pass any data to the 
driver; an explicit "Write Data" call must be made. 

mpleteDependency —This one is called by the “target” 
application, not the source! It tells the driver “hey, I’m interested 
іп whatever's available right now." It basically lets the driver set 
up the "Interested mask" for the dependency properly. I'll say a 
bit more about the "Interested mask" later. 

RemoveDependency —This one is a bit trickier, as it can be 
called by either the source application or the target. If it's called 
by the source, all editions of the data that have been posted get 
totally wiped, and the extent itself is deleted so that any targets 
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that were interested get informed that the data has been blasted 
out from under them (they'll get a “No such dependency" error). 
On the other hand, it may be a single target that's calling. If that 
is the case, the appropriate bit in the “Master Interest mask" (and 
all editions) gets reset (that's one less suitor, darling). When no 
one cares at all anymore (that is, the entire “Master Interest mask" 
goes to zero), the driver will blow away all of the editions just as 
it would if the source removed the dependency. Got all that? 
There’s a quiz next month. 


A reminder that this call does NOT retrieve any data from the 
driver; an explicit “Read Data” call must be made. 

AvailableDependency —I had a truly bad pun for this one, 
butI’ll resist the temptation. This is easy. It just makes the extent 
indicated by the parameters the source to all future defaulted 
“CompleteDependency”s until another dependency is made the 
available one. This has the highly desirable side-effect of making 
it trivial to have more than one target interested in the same 
source. 

Status —Here’s a simple one, too. It just tells whomever is 
calling how many documents have been registered with the 
driver, and how many extents that exist are relevant to the 
document asking for the status (have editions that the target 
hasn't read yet). Its real raison d' etre, though, is to tell the caller 
what version of the driver is installed (ahem). 

Census —is like a high-powered Status. It doesn’t care 
who’s making the call. It just blasts out a list of all the extents that 
it knows of, period. 

WriteData —this is rather like using the clipboard. The idea 
is that you may want to pass data in more than one format. A 
spreadsheet, for example, may wish to pass both the cell selection 
(let's call that type CELL) and a pie chart of the selection (as a 
PICT). Remember, this call is made by the source after it has 
established a dependency. The master interest mask is copied 
from the extent table to the header for the new edition to establish 
which targets have yet to read the new data. 

ReadData — the target’s analog of WriteData, of course. It's 
like SFGetFile inasmuch as it gives a list of preferred data types, 
in order of desirability. The target application makes this call, 
passing the most recent edition number of the data that it received 
last time. If there are one or more editions more recent than that, 
the driver willreturn the latest, marking the "Interested mask" for 
each successive edition as appropriate. It's conceivable (in fact, 
all too likely for some applications, such as databases) that the 
target won't be calling ReadData sufficiently frequently to get 
each and every edition that the source application posts, which is 
why we use editions in the first place. Reading an edition turns 
off the target's bit in the edition-interest-mask, and all older 
editions. An interest mask of zero results in that edition being 
deleted. 


Notes on the code 
This was developed on a Mac Plus running MPW 2.02 
under System 6.0 It should work on any machine running 
MultiFinder, although the technique used in the glue to determine 
if MultiFinder is actually running is not authorized by Apple. 
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Their claim that “you should only check for services you need" 
ignores the fact that in this case the service needed is the 
multitasking capability. A few other matters... 

First, none of the people involved with this project belong to 
the “Names-cost-a-dollar-a-letter” school of identifiers. Hence, 
the verbose identifiers and extensive comments. It was hard 
enough to debug with almost every line commented, believe me! 

Second, the INIT resource is set up so that if you have the 
object to ShowInit by Paul Mercer, you can modify a couple of 
lines and link it in to display start-up icons. We didn’t have 
permission to print his source, and don’t like publishing software 
in MacTutor without every line of source needed to rebuild it, so 
this seems a workable compromise. 

Third, some of the makefiles may have traces of the Odesta 
development environment showing through, even though I tried 
to "genericize" them. I hope they won't be too hard to correct.. 


Bug Fixes and Updates 

Inevitably, bugs will be found in this code, and we already 
have thought of several desirable improvements to add in the 
future (after we're recovered from this exercise in hubris). It is 
not reasonable to expect Dave Smith and MacTutor to act as the 
central exchange for this driver, since the effort involved could 
become significant. 

After January 1st, 1989, we will be acting as IAC Central, 
issuing revised versions as necessary, etc. Bug reports can be sent 
to us immediately (we'd like to think there will never be any, 
but...) along with suggestions for improvements. We сап be 
reached by electronic mail (please, no phones calls!!) at the 
following addresses: 

Paul Snively- СЕпіе: PSNIVELY 

(The first line of any letter should be: 
ATTN: PSNIVELY PAUL SNIVELY for the mail 
server he is using) 

Frank Alviani— GEnie: TOOLSMITH 

Delphi: TOOLSMITH 


In addition, US Snail can reach us (slowly) at the following 
address: 

CodeSmiths 

P.O. Box 8744 

Waukegan, Ill 60079 


We will try and respond in a timely fashion, given the 
constraints of very demanding jobs, a house renovation, and 
small children. 

That about wraps it up for our end. Here — at long last!— 
is the source code for the driver and the glue (in “С”) to simplify 
writing applications to support the protocol! 


Listing: 


# Makefile for the IAC Driver! 
я Frank Alvieni - 8/88 


бгіуег.а 


ob = (ҺІхЕіс) 
directories 
sr = (hlxSrc) 


"Set these definitions to your normal working 
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prog = (hlx) 
e = echo 


*(prog)SAWSInit^ f 
* (sr)SAWSINIT.r^ 
(e) “Date -a -t' Rez IAC >> “(109)” 
Rez -t INIT -c SAWS -o *(prog)SAWSInit^ *(sr)SAWSinit.r^ 


*(ob)SAWSDRVR.a.o^ f  ""(sr)SAWSDRVR.a" 
(e) ‘Date -a -t' Asm SAWSDRVR.a >» “(log)” 
Asm *(sr)SAWSDRVR.a^ -i Me:MPW:AIncludes: -o "(hlxetc)^ 


* (ob)SAWSdrvr.lnk^ *(ob)SAWSInit^ 


"(ob)SAWSdrvr.lnk^ f *(ob)SAWSDRVR.a.o"^ 
(e) “Date -a -t° Link SAWSDRVR.a. >» “(109)” 
Link -t INIT -c SAWS -rt DRVR=31 -sg .IAC “(ob}SAWSDRVR.8.0” 


-о "(ob)SAWSdrvr . Ink” 


*(ob)SAWSINIT.a.o^ f *(sr)SAWSINIT.a" 
(e) “Date -a -t' Asm SAWSINIT.a >> “(log)” 
Asm *(sr)SAWSINIT.a^ -i Me:MPW:AIncludes: -o “(Міхеіс)” 


"(ob)SAWSInit^ |  *(ob)SAWSINIT.a.o" 
(e) “Date -a -t' Link SAWSINIT.a >> “(104)” 
Link -rt INIT=8 -ra 216 "(ob)SAWSINIT.a.o^ -o "(ob)SAWSInit^ 


Listing: SysEnv.a 


Glue for SysEnvirons that was skipped by Apple 
; F. Alviani 
; 7/88 

7 


INCLUDE 
PRINT ON 


‘TRAPS.A’ ;Include Memory manager macros. 


SYSENVIRONSFUNC EXPORT 
movea.] 4(5р2,а0 ;аб contains ptr to world record 
move.w 8(sp),d0 ;90 contains desired version 
-SysEnv irons 
поуеа.1 (sp2*,a0 ;get return addr, remove 
lea 6(5р2,5р ;pop parameters 
move dð, (sp) ;put result in place 
jmp (að)  ;go home 


DC.B 'SYSENVIR" 
END 


Listing: IAC.h 


/*This is the set of externs needed to access the IAC inter- 
fece routines */ 
/*The pointer/handle indicators are only reminders */ 


extern short iac_add_ dependency(C); 
*slot.ID, *hat check, 


/* *doc_ID, 


Xedition */ 


extern short iec.available dependency(2); /% doc_id, hat check 
x 


extern short iac.census(C); 
**extent info */ 

extern short iac_complete_dependency(); /* *doc_id, *slot id, 
*hat. check */ 

extern short iac_open(); 
extern short iac_read_data(); 
hat check, *edition, 


/* *extent. count, 


/* doc_id, slot. id, 


fnt. pref(], *fmt.code, **ext. data */ 
extern short iac_remove_dependency(); 
hat.check */ 
extern short 


/* doc_id, slot. id, 


jac_status(); /* slot. id, 
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*vers. id, *doc count, 


*extent count */ 
extern short iec write. data; /* doc. id, 
hat.check, *edition, 


fmt_count, **ext data */ 


/*error codes for iac_open, etc. */ 
8 define NO.DRIVER -1 

8 define EARLY_SYS -2 

* define MAX ЕХТ5 64 


typedef struct ( 
long  doc.ID; 


short hat check; 
short ed level; 
) info.rec; 


typedef struct ( 
info.rec ext entry (MAX EXTS1; 
) info -tbl, *info_tb1P, **info tblH; 


Listing: IAC.c 
хаж 
x 
x File: IAC.c 
x 


* Package: Inter Application Communications 
x 


* Description: interface package to the driver for the use of 


x application programs. 
* 


* Author(s): 
*FEA 6/19/88 
x 


*/ 


include 
include 
include 


8 <types .h> 
t 

tt 

8 include 

t 

8 


«files.h»? 
<memory . h? 
«osutils.h? 
«ser ial.h» 
‹1ас.һ› 


include 
include 


define MIN.BLK. SIZE 0хС 
® define DEBUG false 


static short iac_ref_num; 


/** 
* Routine: iac_open 
x 


ж Тһе IAC driver is opened by this call and the ioRefNum 
Ж saved so it doesn’t need to be passed with all calls. 
х A null value is returned if the open is successful; 
*otherwise the operating system error is 

* returned. 

*/ 


short 1ас_ореп() 


( 
SysEnvRec  theWor ld; 
/* ALMOST complete knowledge about the world */ 


THz s_ZoneP, a .ZoneP; /* so we can check zone adjacency 
*/ 

05Егг the. err; 

short result - 0; 


the_err = SysEnvironsC1, &theWorld); 


if CtheWorld.systemVersion < 0х0420) /* too early! */ 
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result = EARLY.SYS; /% “no multifinder^ */ 


else 


/*check for multifinder active by checking if system zone 
is adjacent to application zone, which never happens under 
MultiFinder. 
x/ 


s_ZoneP = SystemZone(); 

а_7опеР = ApplicZone(); 

if С CClong) s_ZoneP->bkLim + МІМ ВІК 517Е) == (long) 
а 2 


result = EARLY_SYS; 
/* zones adjacent - по multifinder */ 


else /* now try to ectually open the IAC driver */ 


SusBeep( 1); 
result = OPENDRIVERC^Yp.IAC^, &iac.ref лит); 


) 


return(result); 


/** 

х Routine: iac -add dependency 

x 

* This is used to inform the ТАС driver that а new 
*dependency has been established and should be 

*added to its internal tables. A null value is 

*returned if the open is successful; otherwise the operating 
*system error is returned. 


х/ 


short iac_add_dependency(doc_id, 3104-19, hat check, edition) 
long *doc_id; 
/* identifies the source document (permanent) */ 
short *slot id; 
/* identifies the source document (session) */ 
short *hat check; /* extent identifier */ 
short *edition; 
/* how many times extent has changed (session) */ 


10Param the_blk; 
05Егг {ће_егг; 
struct ( 


short func; 

long doc. id; 
short slot.id; 
short hat check; 
short edition; 
my_params; 


wt 


* if DEBUG 
returnCthe.errznoErr); /* short circuit testing without MF */ 
8 endif 


my_params.func = 1; 
x/ 

my-params.doc.id = *doc_id; 

ny-params.slot.id = *slot. id; 

ny-parems.hat.check = *hat check; 


/* set up private parameter block 


the-blk.ioCompletion = nil;/* setup driver parametr block */ 
the-blk.ioRefNum = iac.ref num; 

the-blk.ioBuffer = &my_params; 

the_bik.ioReqCount = sizeof (my_params ); 

the_blk.ioPosMode = fsFromStart; 
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the. blk.ioPosOffset = 0; 
the_err = PBWriteC&the blk.qLink, false); 
/* add the dependency */ 
if (the. err == noErr) /% update output parameters */ 
*doc.id = my_params.doc_id; 
*slot id = my_params.slot_id; 
*hat check = my_params .hat—check; 
Xedition = my_params.edition; 


) 


return(the_err ); 


[** 
х Routine: iac.complete dependency 


* 
* This is used to inform the ТАС driver of a document that 
Ж is interested іп a particular dependency. А null value is 
* returned if the open is successful; otherwise the 

* operating sustem error is returned. 

х/ 


short iac_complete_dependency(doc_id, slot_id, hat check) 
long Хаос. id; 

/* identifies the source document (permanent) */ 
short *slot 14; 

/* identifies the source document (session) */ 
short *hat check; /* extent identifier */ 


І0Рагат the-blk; 
OSErr the. err; 
struct ( 


short func; 

long doc. id; 

short slot.id; 

short hat. check; 
} mu-params; 


® if DEBUG 

return(the_err=noErr ); 
/* short circuit for testing without MF */ 
8 endif 


my_params .func = 2; 
х/ 

my_params.doc_id = *doc.id; 

ny-parems.slot id = *slot_id; 

mu-params.hat_check = *hat check; 


/* set up private parameter block 


the-blk.ioCompletion = nil;/* setup driver parametr block */ 
the_blk.ioRefNum > iac.ref num; 
the.blk.ioBuffer = &my_params; 
the_bik.ioReqCount = sizeof (my_params); 
the_blk.ioPosMode = fsFromStart; 
the-blk.ioPosOffset = 0; 
the_err = PBWriteC&the blk.qLink, false); 
/* complete the dependency */ 
if (the_err == noErr) /% update output parameters */ 
*doc_id = my_params.doc_id; 
*slot_id = my_params.slot_id; 
*hat check = my-params.hat check; 


) 


returnCthe. err); 
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[** 
х Routine: iec.remove. dependency 


This is used to inform the IAC driver that a document is 
no longer interested in а particular dependency. If the 
document is the original source all “targets” will be 

* informed that there is no longer any such 

*extent; if 811 targets lose interest the source will be 

* informed that it no longer needs to update the extent. 

х/ 


short iac_remove_dependency(doc_id, slot id, hat check) 
long doc. id; 

/* identifies the source document (permanent) */ 
short slot id; 

/* identifies the source document (session) */ 
short het сһеск; /* extent identifier */ 


е »* »* 3 


( 

ІОРагат the blk; 
05Егг {ће_егг; 
struct ( 


short func; 

long doc_id; 

short 5104 14; 

short heat. сһеск; 
} my_params; 


8 if DEBUG 


return(the_err=noErr); /* short circuit testing without MF */ 
® endif 


my-params.func = 3; /* set up private parameter block */ 
my_params.doc_id = doc.id; 

my_params.slot_id = slot. id; 

mu-params.hat. check = hat check; 


the-blk.ioCompletion = nil; /* setup driver paramtr block */ 
the-blk.ioRefNum = iac.ref num; 
the.blk.ioBuffer = &mu-params; 
the blk.ioReqCount = sizeof (my. params?; 
the-blk.ioPosMode = fsFromStart; 
the-blk.ioPosOffset = 0; 
the-err = PBWriteC&the blk.qLink, false); 
/* remove the dependency */ 


returnCthe. err); 


/** 
* Routine: iec.evailable dependency 
x 


* This sets the indicated extent as the “available extent 
*to be used as the source for future defaulted 

*^complete dependency^ calls. 

*/ 


short iac_available_dependency(doc_id, hat_check) 
long doc_id; /* identifies the source document (permanent) */ 
short hat check; /* extent identifier */ 


( 

І0Рагат the. blk; 
05Егг {ће_егг; 
struct ( 


short func; 

long doc. id; 

short hat. check; 
) my-params; 


" if DEBUG 
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returnCthe егг-поЕгг ); 
/* short circuit for testing without MF */ 
Я endif 


my_perams.func = 4; 
*/ 

mu-params.doc-id = doc_id; 

my_params .hat_check = hat. check; 


/* set up private parameter block 


the_blk.ioCompletion = nil;/* setup driver parametr block */ 
the_bik.ioRefNum = iec.ref num; 
the_bik.ioBuffer = &my_params; 
the-blk.ioReqCount = sizeof (my_params ); 
the-blk.ioPosMode = fsFromStart; 
the_blk.ioPosOffset = 0; 
the_err = PBWriteC&the blk.qLink, false); 
/* this dependency is now “available” */ 


return(the_err); 


хх 
х Routine: iec.status 
x 


* This allows the application program to find out what's 
*going on. 
*/ 


short iac_status(slot_id, vers_id, doc count, extent—count) 

short slot.id;  /* identifies the inquiring document 
(session) */ 

short *vers id; /* driver version*100 */ 

short *doc.count;  /* count of active documents */ 

short *extent count; /* count of extents relevant to 
inquiring doc */ 


ТОРагат the-blk; 
OSErr X the.err; 
struct ( 


short func; 

short slot.id; 

short vers.id; 

short doc.count; 

short extent. count; 
} mu-params; 


8 if DEBUG 


return(the_err=noErr); /* short circuit testing without MF */ 
8 endif 


my-perams.func = 5; 
*/ 
my-params.slot.id = slot. id; 


/* set up private parameter block 


the_blk.ioCompletion = nil;/* setup driver parametr block */ 
the-blk.ioRefNum = іас_геѓ num; 
the_blk.ioBuffer = &my parems; 
the-blk.ioReqCount = sizeof (my. parems); 
the. blk.ioPosMode = fsFromStart; 
the-blk.ioPosOffset = 0; 
іһе-егг = PBRead(&the_blk.qLink, false); 
/* read ТАС status */ 
if Cthe.err == noErr) /% update output parameters */ 
*vers id = my_params.vers_id; 
*doc_count = my_params.doc_count; 
*extent_count = my-parems.extent count; 


return(the_err); 


167 


/** 
x Routine: iac.census 
x 


* This provides identifying info for all registered extents. 
*/ 


short iac.censusCextent count, extent info) 
Short ^ *extent.count; /* count of extents registered */ 
info_tbIP extent info; /* Ptr to table of info for each 
extent */ 


ІОРагат the_bik; 
05Егг іһе. егг; 
short i; 
struct ( 
short func; 
short extent count; 


info.rec extent info[MAX ЕХТ51; 
) my_params; 


# if DEBUG 
return(the_err=noErr); 

without MF */ 

# endif 


/* short circuit for testing 


my-perems.func = 6; /* set up private parameter block 
*/ 


the-blk.ioCompletion = nil; 
block */ 

the-blk.ioRefNum = iac.ref num; 

the-blk.ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof (my. parans); 

the-blk.ioPosMode = fsFromStart; 

the-blk.ioPosOffset - 0; 

the_err = PBReadC&the blk.qLink, false); 
/* read IAC status */ 


/* set up driver parameter 


if (the.err == noErr) /* update output parameters */ 


*extent. count = my.parems .extent. count; 
BlockMove (&my parems extent info[0), 
(Ptr) extent info, 
(long) my-perems.extent count * sizeofCinfo.rec)); 


returnCthe. err); 


/** 
х Routine: iac write. data 
x 


* This updetes the data for the specified extent, resulting 
Жіп а new change level. 
x 


short iac_write_dataCdoc_id, hat check, edition, fmt count, 
ext_data) 
long doc_id; /* identifies source document (permanent) */ 
short hat check; /* extent identifier */ 
short *edition; /* how many times extent has changed 
(session) */ 
short fmt count; /* number of formats being written */ 
Handle ext_data; /* Handle to actual data */ 


IOPeren the_blk; 
05Егг the-err; 
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struct ( 
Short func; 
long doc. id; 
short hat check; 
Short edition; 
short fmt count; 
Handle the. dataH; 
) my_params; 


* if DEBUG 
return(the_err=noErr ); 

without MF */ 

® endif 


/* short circuit for testing 


ny-params.func = 7; /* set up private parameter block 
*/ 
mu-params.doc-id = doc_id; 
ny-parems.hat check = hat check; 
ny-parems.fmt count = fmt count; 
my_params.the_dataH = ext data; 


the-blk. ioCompletion = nil; 
block */ 

the-blk.ioRefNum = iac.ref num; 

the-blk.ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof(my.parems); ; 

the-blk.ioPosMode = fsFromStart; 

the-blk.ioPosOffset = 0; 

the_err = PBWrite(&the blk.qLink, false); 
/* update dependency */ 


/* set up driver parameter 


if (the err == noErr) /* update output parameters */ 


Xedition = my_params.edition; 


returnCthe err); 


/** 
x Routine: iac.read data 
x 


* This is used to retrieve the actual data Гог the latest 
*change_level for the specified extent. The IAC driver will 
*record that the inquiring document has read the data. 

x 


*ext.data will be resized by the driver to hold the data. 
ud 


short iacread_dataCdoc_id, slot id, hat check, edition, 
(ті. рге”, 
fmt_code, ext data) 

long doc. id; /* identifies the source document (perma- 
nent) */ 

short slot id; 
sion) */ 

short hat check; 

short *edition; 
(session) */ 

long fmt-pref [3]; /* preferred formats, descending desira- 
bility */ 

long *fmt code; 

Handle ext. date; 


/* identifies the source document (ses- 


/* extent identifier */ 
/* how many times extent has changed 


/* format returned to caller */ 
/* Handle to actual data */ 


10Param the_bik; 
OSErr {ће_егг; 
struct ( 


short func; 
long doc. id; 
short slot id; 
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short hat check; 

short edition; 

long fmt. pref [3]; 

long fmt_code; 

Handle ext_data; 
} my-parems; 


* if DEBUG 
return(the_err=noErr ); 

without MF */ 

® endif 


/* short circuit for testing 


my_params.func = 8; /* set up private parameter block 
x 
my_params.doc_id = doc.id; 
my_params.slot_id = slot. id; 
my-perems.hat check = hat check; 
my_params .edition = *edition; 
my-params.fmt pref(2] = fmt_pref [9]; 
my-perams.fmt pref[1] = fmt_pref (1); 
my_params.fmt_pref(2] = fmt pref [2]; 
my-parems.ext data = ext data; 


the-blk.ioCompletion = nil; 
block */ 

the-blk.ioRefNum = iac.ref num; 

the blk.ioBuffer = &my params; 

the-blk.ioReqCount = sizeof Cmy_params ); 

the-blk.ioPosMode = fsFromStart; 

the. blk.ioPosOffset = Ø; 

іһе-егг = PBRead(&the_blk.qLink, false);/* read the data */ 


/* set up driver parameter 


if Сіһе err == noErr) 


*edition = my_params.edition; 
*fmt code = my. parens.f mt. code; 


) 
returnCthe err); 
Listing: SAWSDRVR.a 


н ыыы ы ы н н а н ыыы а ын ынын ыы ын ES EES 


‚***** The SAWS Inter-Application Communication Driver 
ЖЖЖЖЖ 

;***** Written with blazing speed 6-8/88 by Paul F. Snively 
,***** With one HECK of а lotta help from Frank Alviani 

xxx 


е and Mike Walsh 2554; 
SOOOOOODOODOEDODEOOOOOOOOEOODOCODOEIDOOEOEOOOOOOEEOOOOEOOEOOOOOEROEOK 


J 

;Modif ication History: 

36/19/88 First Draft-1.0D1-Paul F. Snively 

; 7/10/88 Second draf t-1.ØB1-Paul F. Snively & Michael К. 
¿Walsh 

;8/T/88 Yet another crack at it-1.0B1-Paul F. Snivelu & 
; Frank Alviani 

;8/8-21/88 Final Debugging - Frank Alviani 


“Basically this puppy is the DRVR resource that actually 
; implements Frank’s cool ideas that are documented in the 
; article that accompanies this listing. 

INCLUDE 


INCLUDE 
INCLUDE 


‘Traps .8’ 
‘QuickEqu.a’ 
‘SysEqu.a’ 
INCLUDE ‘SysErr.a’ 
INCLUDE ‘ToolEqu.a’ 
STRING PASCAL 


NumOfDocs EQU 32 
NumOfExtents EQU 64 


Мах of 32 documents 
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Unimpl EQU $9F 
OSDisp EQU $8F 
DummyID EQU 1 


¿For testing environment 


NoMoreDocs EQU -2000 ^ ;This one isn't used-yet 
NoMoreSlotsEQU -2001 ¿Neither is this one-yet 
WriteFailedEQU -2002 ‚Ог this one... 
MissingLinkEQU -2003;Үеі another SAWS-def ined error 
NoNewerEdition EQU -2004 ; YASAWSE 

ReadFailed EQU -2005 ; SASAWSE 

NoSuchDep EQU -2006 

OldROMs EQU -2007 


ExtentRec RECORD 0 
DocID DS.L 1;Home document for this extent 
HatCheck 05.0 1  ;Unique ID for this extent 
Edition DS.W 1 ; The edition number 
MstrInterestMsk DS.L 1 ,Master Interest Mask 
EditionListDS.L 1 ;Edition List 
ExtentSize EQU * 

ENDR 


EditionHdr RECORD 0 
NextEd 05.11 ;Handle to next Ed 
InterestMask DS.L 1 ;Mask for this particular Ed 
NumFormats DS.W 1 ;How many formats stored? 
EdInstancesDS.L 0 ;Instances start here 
EditionSizeEQU * 

ENDR 


IACGlobals RECORD 0 
ExtentCountDS.W 1 ;Number of extents extant 
ExtentTableDS.L NumOfExtents*ExtentRec .ExtentS ize 
DocIDs DS.L Num0fDocs;Unique Document identifiers 
AvailDependency DS.L 1 ;Offset of currently available depend- 
ency 
IACGlobalsSize EQU * 
ENOR 


DriverEntryPROC ; See Device Manager IM:2 
IMPORT DriverOpen, Dr iverPr ime 
IMPORT DriverCt1,DriverDone 
IMPORT DriverClose 


DC .BC1<<dReadEnable) + (1<<dWritEnable) ; We handle reads/ 
writes 


DC.B9 ; Lower byte is unused 
DC.W0*60 ; Ø sec periodic update 
06.40 ; We don’t do events 

06.10 ; No menu for this accessory 


DC .WDriverOpen-Dr iverEntry ; Open routine 


DC .WDriverPrime-DriverEntry ; Prime 
DC.WDriverCtl-DriverEntry ; Control 
DC .WDriverDone-Dr iverEntry ; Status - unused 
DC .WDriverClose-DriverEntry ; Close 


DC.B °. IAC’ ; The name of our driver 
ALIGN 2 ; Word align 
ENDPROC 


DriverOpen PROC 
IMPORT IACGlobalsSize 


TST.W ROM85 
BGE.S 6! 

MOVE .W #01dROMS, DO 
BRA.S ExitÜpen 


0124 ROMs? 
jno, keep going? 


61 
with  IACGlobals 
TST.L dCtlStorageCA1) ;Did we already allocate our 
space? 


BNE.S ExitOpen /ІҒ so, then we're already open 
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MOVE.L #IACGLobalsSize,DØ ;How much global space do we 


want? 
-NewHandle sys,clear ;Try to allocate it 
BNE.S ExitOpen ;Fail miserably since error 
occurred 
e2 
MOVE.L Ag,dCtlStorageC(A1) ;Otherwise store handle 
MOVE.W "Q,ExtentCount — ;We start with zero extents 
endwith ; IACGlobals 


ExitOpen 
RTS ¿We're outta here 
ENDPROC 


Dr iverClosePROC 
IMPORT WipeExtentData 
MOVE.L 06115%огаде(А 10,00 ;Get our global handle 
BEQ.S ExitClose ;If we don’t have one, leave! 
MOVEA.L 00,А6 ;Otherwise get into address 
register 


with IACGlobals 


MOVE.W ExtentCount(A6),D7 ;How many extents are there? 


LEA ExtentTableCA6),A9 ;Point to the ExtentTable 
MOVE . А0,06 бес it in the right register 
endwith ; IACGlobals 


WalkExtents 
MOVEA.L 06,А0 бей Extent Pointer 
JSR WipeExtentData ;К111 its data 


NextExtent 
with  ExtentRec 
SUBQ.W 81,07 ;Decrement extent counter 
BEQ.S EndClose ;And continue until done 
ADD.L fExtentSize,D6 Роіпі to next extent 
BRA.S WalkExtents  ;And loop 
endwith ;ExtentRec 


EndClose 
MOVEA.L 9С41${огаде(А1), Аб ;Get our globals handle 
-DisposHandle ¿And get rid of it 


ExitClose 
RTS ¿Back to celler 
ENDPROC 


f This is the main entry point for ALL functions of the driver 


Dr iverPrimePROC 
IMPORT Dr iverAddDependency, Dr iverCompleteDependency 


IMPORT Dr iverRemoveDependency, Dr iverRemoveDependency 


IMPORT DriverAvailebleDependency, Dr iverStatus 
IMPORT DriverCensus, DriverWriteData 
IMPORT DriverReadData 


MOVEA.L dCtlStorage(A12,A6 ;Get our global handle 


MOVEA.L ioBufferCA@),A4  ;Get the address of the “data” 


MOVE.W (А42,00 ;Get the routine identifier 
ADD.W 00,00 Multiply it by two 
MOVE .W RoutineTableCD22,DO ;Get routine offset 
JSR RoutineTableCDO) ;Go to the proper routine 
MOVE.L JIODone,-CA7) ;wrap up 
RTS 

RoutineTable 
06.80 ; 1-Базед function codes... 
DC.WDriverAddDependency-RoutineTable 
DC.WDriverCompleteDependency-Rout ineTable 
DC.W DriverRemoveDependency-Rout ineTable 
DC.WOriverAvailebleDependency-Rout ineTable 
DC.WDriverStatus-RoutineTable 
DC .WDriverCensus-Rout ineTable 
DC.W Dr iverWriteData-Routinelable 


170 


DC.WDriverReadData-Rout ineTable 
ENDPROC 


; This routine adds the source of а link to the dependency 
teble 


Dr iverAddDependency PROC 
IMPORT F indSlotID 


AddDepRec RECORD 0 
Func 05.41 
docID DS.L 1 
Slot. ID DS.W 1 
hatCheck DS.W 1 
edition 05.0 1 
AddDepRecSizeEQU * 
ENDR 


MOVEA.L (462,42 бес globals pointer 
(ҒА IACGlobals.DocIDsCA22,A3 ;Point past end of 
extentTable 
LEA IACGlobals.ExtentTableCA2),A2;Point to base of 
extent table 
MOVEQ #0,02 ;Clear our counter 
AddDepLoop 
TST.L ExtentRec.docIDC(A2)  ;Is this slot available? 
BEQ.S FoundAvailSlot 21Ғ so, we're done looking 
ADD.L fExtentRec.ExtentSize,D2 ;Maintain “available” 
offset 
ADDA.L *ExtentRec.ExtentSize, A2 ;Else point to next 


record 
CMPA.L А2,АЗ ;Are we done? 
BGT.S AddDepLoop ;If not, look again 
АаФберҒа11 
MOVE.W ЗМоМогебосв,00 ;Return custom 05Егг 
BRA AddDepExit Апа leave 


FoundAvailSlot 
MOVE.L AddDepRec.docIDCA4),D8 ;Get the docID 
BNE.S ExistingDocID 60 if it already exists 
MOVE .L Time,D® ;Else copy it from low RAM 
MOVE .L D®@,AddDepRec.docIDCA4)  ;Updete param block 


ExistingDocID 
MOVE.L DO, ExtentRec.docIDCA2)  ;Store the docID 
MOVE .L 00,05; Save for later 
MOVE.L A2,D4 ;бауе extent-rec addr for 
leter 
MOVE.W AddDepRec.slot_IDCA4),D1;Did we get passed а 
slot. ID? 
BEQ.S NeedASlot 060 get one if not 
MOVE.L (Аб), АЗ 
LEA IACGlobels.DocIDSCA32,A3 ;Pt to table of unique 
IDs 
SUBQ.W * 1,01 ; Adjust index to В-Базед 
LSL.W 82/01 ;Convert to offset 
CMPI.L *OummyID,0(A3,D1.W) ,15 passed slot ID target 
only? 
BEQ.S HaveASlot ,Yes, put in real docID 
CMP.L ØCA3,D1.W),D5 10 in table OK? 
BEQ.S HaveASlot Уез, use 810010 as is 
NeedAS lot 
BSR FindSlotID бей a valid slot ID 
BLT.S AddDepExit ‚№ slots - Leave 
HaveAS lot 
MOVE.L D5,0CA3,D1.W) ;Ѕауе docID in slot 
MOVEA.L (462,42 ;Dereference global handle 
MOVE .W DØ, AddDepRec.slot_IDCA4) ;Store the slot ID 
MOVE .W AddDepRec.hatCheckCA42,D1 ;Is there already а 
hatCheck? 
BNE.S StuffHatCheckCalc ; І? so, bypass calculation 
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LEA IACGlobals.docIDsCA22,A3 ;Point past the end 
LEA IACGlobals.ExtentTableCA2),A2;Point to right 
place 


; Search for highest hatCheck registered for this docID 
MOVEQ #0,D1 ;Initialize counter 
MOVE.L AddDepRec.docIDCA4),D8 ;Get the docID again 


HatCheckLoop 
CMP.L ExtentRec.docIDCA22,D0  ;Is the docID the same? 
BNE.S NotSeme ;No, ignore 
CMP.W ExtentRec.hatCheck(A2),D1 ;Compare hatChecks 
BGE.S NotSame ;бо if no need for update 
MOVE .W ExtentRec.hatCheck(A2),D1 ;Save max hatCheck 
NotSame 
ADDA.L #ExtentRec.ExtentSize,A2 ;Point to next record 
CMPA.L A2,A3 ¿Are we done? 
BGT.S HatCheckLoop ‚бо if not 
ADDQ.W *1,01 ;Bump to next hatCheck 
MOVE.W D1,AddDepRec.hatCheck(A4) ;Update param block 


Stuf f HatCheckCalc 
MOVEA.L 04,А2 ¿Point to “working” extent 
MOVE.W D1,ExtentRec.hatCheckCA2) ;Store hatCheck 
MOVE.W 80 AddDepRec .editionCA4) ;Pass back edition zero 
MOVE .W #0, ExtentRec .editionCA2) ;Set edition zero 
MOVEA.L (A6),A2 ;Get globals pointer 
MOVE.L 02, IACGlobals.AvailDependency(A22; It's also the 

available dependency 

ADD.W *'*1,IACGlobals.ExtentCount (A2) 
MOVE .W ЗпоЕгг,00 ¿We succeeded! 

AddDepEx i t 
RTS 


ENDPROC 


This routine adds the destination to а link that’s been 
started. If a passed-in slot. ID conflicts with an existing 
entry, it is re-assigned 
riverCompleteDependency PROC 
IMPORT F indSlotID 


Wwe we Ve Ge 


CompDepRec RECORD 0 
Func DS.Wi 

docID 05.11 

Slot. ID DS.W1 
hatCheck DS.W 1 
CompDepRecSize EQU * 


ENDR 
MOVEA.L (462,42 ;Dereference globals handle 
MOVE.L CompDepRec.docIDCA42,D0 ;Get the passed docID 
BNE.S HaveDocID ‚бо if we were passed docID 
MOVE.L IACGlobals.AvailDependencyCA22,01;Get available 
dependency 
LEA IACGlobals.ExtentTableCA2),A2;Point to extent 
records 


MOVE.L ExtentRec.docIDCA2,D1.L),D8 ;Get the docID 
with CompDepRec 
MOVE.L DØ, дос10(А4) ;Return to sender 


HaveDocID 
MOVE.W 5104. 10(А42,01 ;019 we get passed а slot. ID? 
BNE.S ExistingSlotID ;бо get one if not 


MOVE.L #DummuID,D3 ;Use dummy ID in slot for now 
BRA.S NeedSlotID ‚бо find slot to put it in 
ExistingSlotID 
.  MOVE.L (Аб), АЗ 
LEA IACGlobals.DocIDSCA3),A3 ;Pt to table of unique 


IDs 
SUBQ.W 81,01 ;Adjust index to 8-based 
LSL.W 42,01 ;Convert to offset 


CMPI.L DummyID,OCAS,D1.W) ;Іѕ passed slot_ID а dummy? 
BNE.S CheckSlotID (Мо, see if it’s OK 
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MOVE.L D2,0CA3,D1.W) ;Yes, replace with real thing 
CheckSlotID 
CMP.L 9CA3,D1.W),D8 ;DocIDs match? 
BEQ.S HaveSlotID 
NeedSlotID 
BSR FindSlotID ;Get а valid slot ID 
BLT.S CompDepExit ;failed... 
HaveSlotID 
MOVE М D@,slot_IDCA4) ¿Store slot_ID in caller’s 
block 
MOVE.L docIDCA4),D3 
endwith ; CompDepRec 
MOVE.L 03, CA3,D1.W) ;Store docID 
MOVEA.L (462,42 ;Dereference globals handle 
MOVE.L IACGlobals.AvaiDependencyCA22,D2 ;Get available 
dependency index 
LEA IACGlobals.ExtentTableCA2),A2;Point to extent 
records 
with ExtentRec 
MOVE.L MstrInterestMsk(A2,D2.L),D3 ;Use register to 
address 811 32 bits 
BSET 00,03 бей the interested bit 
MOVE.L 03,MstrInterestMsk(A2,D2.L) ;Васк into table 
MOVE.L EditionList(A2,D2.L),D1  ;Get the “Edition List 
handle” 
BGT.S WalkEditions®  ;If it's a handle, deal with it 
MOVE .W #NoSuchDep, 00 ;set error code 
ВЕ0.5 CompDepExit ;If it’s zero, we do nothing 
MOVE.L *Q,EditionListCA2,D2.L) — ;Otherwise give it no 
respect 
BRA.S CompDepExit 
endwith ;ExtentRec 


WalkEditions® 
MOVE .W ExtentRec.HatCheck(A2,D2.L),D3 
MOVE .W 03, CompDepRec .hatCheck(A4) ;Return to caller 
WalkEditions 
MOVEA.L 01,АЗ ;Copy the handle 
MOVEA.L (АЗ),АЗ ;Dereference the handle 
with  EditionHdr 
MOVE.L InterestMask(A3),D3 “So we can use 32-bit mode 
BSET 00,03 ;Set the appropriate bit 
MOVE.L 03, InterestMaskCA3) 
MOVE.L NextEdCA3),D1 бей handle to next handle 
endwith ;EditionHdr 
BNE.S WalkEditions ;If there is one, deal with it 
MOVE. W ®noErr , 0 Ме succeeded! 


CompDepEx i t 
RTS 
ENDPROC 


; This routine severs а link and removes it from the tables 
Dr iverRemoveDependencyPROC 
IMPORT F indExtentByDandHC , WipeExtentData 


RemovDepRecRECORD 0 
Func 05.01 

docID 0511 
slotID 05.01 
hatCheck DS.W 1 
RemovDepRecSize EQU * 


MOVEA.L (A6),A2 ;Dereference globals handle 

MOVE.L RemovDepRec.docIDCA42,D0 ;Get the passed docID 

MOVE.W RemovDepRec.hatCheck(A4),D1 ;Get the passed 
hatCheck 

JSR FindExtentByDandHC ;Find the extent 

BNE.S RemovDepExit ;Use FEBAHDC’s errcode and scram. 
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MOVEA.L (А62,А2 ,Dereference globals handle 
LEA IACGlobals.ExtentTableCA22,A2;Get table base 
MOVE.L ExtentRec.MstrInterestMskCA2,D2.L2,D3 ;Get 
interest mask 
MOVE.W RemovDepRec.slotIDCA42,D4 ;Get the passed $10410 
BCLRD4,D3 ;Declare this slot uninterested 
BNE.S RemovTarget ;If bit WAS set, target was 
doing the removing.. 
RemovSource ,.Otherwise it’s the source. 
MOVEA.L ExtentRec.EditionListCA2,D2.L2,A0 ; Stuff list 
header into А0 
JSR WipeExtentDeta Kill the extent’s data 
LEA IACGlobals.ExtentTableCA2),A2;Get table base 
with  ExtentRec 
MOVE.L 80 бос10(А2,021) ;Clear DocID 
MOVE.L *g,HatCheckCA2,D2.L) ;Clear HatCheck/Edition 
MOVE.L *8,MstrInterestMsk(A2,D2.L) ;Clear 
MstrInterestMsk 
MOVE.L *Qü,EditionList(A2,D2.L) ;С1еаг EditionList 
endwith ;ExtentRec 
MOVE.W ЗпоЕгг,00 
BRA.S RemovDepCleanup 
RemovTarget 
TST.L D3 ¿Does anybody саге? 
BEQ.S RemovSource ;If no, then go to sleep 
MOVE.W #noErr,DØ ;Set return code 
RemovDepCleanup 
MOVE.W RemovDepRec.slotIDCA4),D4 ;Get the passed slotID 
SUBQ.W 81,04 
LSL.W 82/04 
MOVEA.L (462,42 
with IACGlobals 
SUBQ.W #1, ExtentCount(A2) ;0пе less extent in world 
LEA DocIDsCA2),A2 ¿Point to table of unique IDs 
MOVE .L #8, 8CA2,D4.W) ¿Clear doc’s slot 


jSet return code 


¿Turn into offset 
;Dereference globals handle 


endwith ;IACGlobals 
RemovDepExit 

RTS ; Bye-bye 

ENDPROC 


This routine marks a link source as “available for 
completion” 


Cw<- w... м. 


riverAvailableDependency PROC 
IMPORT FindExtentBuDandHC 


AvailDepRecRECORD 0 

Func DS.W1 

docID DS.L 1 

hatCheck DS.W 1 

AvailDepRecSize EQU * 
ENDR 


MOVEA.L (A6),A2 ;Dereference globals handle 

MOVE.L AvailDepRec.docID(A4),D0 ;Get the passed docID 

MOVE.W AvailDepRec.hatCheck(A4),D1 ;Get the passed 

hatCheck 

JSR FindExtentByDandHC бей dependancy if it 
exists 

BNE.S AvailDepExit 

MOVEA.L (А62,А2 

MOVE.L D2, IACGlobals.AvailDependency(A2) ;Otherwise, we 

have a winner! 

jset return code 


;If subr plotzed get out. 


MOVE.W ЗпоЕгг,00 
AvailDepExit 
RTS j Bye-bye 


ENDPROC 


; This routine lets the client know what's happening 


2 
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DriverStatus PROC 


StatusRec RECORD 0 


Ғиыпс DS.W1 
slotID DS.W1 
versID 05.01 


docCount DS.W 1 
extentCountDS .W 1 
StatusRecSizeEQU * 


ENDR 


MOVEA.L (462,42 ;Dereference globals handle 
MOVE.W StatusRec.slotIDCA42,00 ;беї slotID 

MOVE .W * 120, StatusRec.versIDCA4) ;Report version as “100” 
LEA IACGlobals.Avai 10ерепдепсу(А2 ), A3 ;Point past end 

LEA IACGlobais.DocIDSCA2),A2 ;Point to extent table 

MOVEQ 80 03 ;Clear our counter 


CountDoxLoop 
TST.L @CA2) ;Is the docID for real? 
BGE.S CountDoxSk ip If neg, then а modern date 
А000 # 1,03 -50 add 1 to the count 
CountDoxSk ip 


ADDA.L 84, А2 ;Else point to next record 
CMPA.L A2,A3 ;Аге we done? 
BGT.S CountDoxLoop ;If not, look again 


MOVE.W D3,StatusRec.docCount(A4) ;Report number of docs 


MOVEA.L (462,42 ;Dereference globals handle 

LEA IACGlobals.DocIDsCA2),A3 ;Point past end 

LEA IACGlobals.ExtentTableCA2),A2;Point to extent 
table 


MOVEQ 80/03 ;Clear our counter 


CountExtLoop 


with ExtentRec 

MOVE .L MstrInterestMsk(A2),D4 
BTST.L 00,04 ;1$ this slot interested? 

BEQ.S CountExtSkip ІР not, then get next extent 
MOVEA.L EditionListCA2), АВ ;Get EditionList HANDLE 
endwith ;ExtentRec 


¿Fetch interest mask 


FindExtLoop 


MOVE.L А0,04 

BEQ.S CountExtSk ip 
MOVEA.L (Аб), Аб 
MOVE.L EditionHdr.InterestMaskCA2),04 

BTST.L 00,04 16 this edition interested? 
BEQ.S FindExtSkip Мо, so check next extent 
ADDI.L 81,03 ;Yes, edd 1 and.. 

BRA.S CountExtSk ip ;.Get out 


¿valid address? 
Мо more editions, get out 


FindExtSk ip 


MOVEA.L EditionHdr.NextEdCA2),A0 ;Move next EditionList 
in 


BRA.S FindExtLoop ¿And test back there.. 


CountExtSk ip 


ADDA.L 8ExtentRec.ExtentSize, A2 ;Else point to next 
record 

CMPA.L А2, АЗ ;Аге we done? 

BGT.S CountExtLoop ;If not, look again 

MOVE.W D3,StatusRec.extentCount(CA4) ;Report number of 


extents 
StatusExit 
MOVE.W 80/00 ;Indicate exit OK 
RTS 
ENDPROC 


2 
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; This routine returns а count of active programs, links, etc. 


to the client 


Dr iverCensus PROC 


Census ІКес RECORD 0 
docID DS.L 1 


edition 


DS.W 1 
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hatCheck DS.W 1 
Census IRecSize EQU * 
ENOR 


CensusRec RECORD 0 
Func DS.W1 
extentCountDS.W 1 
Census 1 DS.B Census 1Вес 
CensusRecSizeEQU * 

ENDR 


MOVEA.L (A6),A2 ;Dereference globals handle 
MOVE.L *CensusRec.Census1,D4 ;0ffset to write for 
output recs 
LEA IACGlobals.DocIDsCA2),A3 ;Point past end 
LEA IACGlobals.ExtentTableCA2),A2;Point to extent 
table 
MOVEQ #0,D3 ;Clear our counter 
CensusLoop 
TST.L ExtentRec.docID(A2) ;Сћеск this extent”? docID 
BEQ.S CensusSkip ¿If wrong, skip to next 
with  ExtentRec 
MOVE.L docIDCA2), Census IRec.docIDCA4,D4.L) ;Move docID 
MOVE.L EditionCA2), Census IRec .editionCA4,D4.L) ,Move 
edition 
MOVE.L HatCheck(A2), Census IRec.hatCheck(A4,D4.L) — ;Move 
hatCheck 
endwith ;ExtentRec 
ADDI.L *tCensus 1ІКес. Census lRecS ize, D4; Move to next output 
rec 
ADDQ.W 81,03 
CensusSk ip 
ADDA.L *ExtentRec.ExtentSize,A2 ;Else point to next 


record 
CMPA.L А2,АЗ ;Are we done? 
BGT.S CensusLoop И! not, look again 
CensusExit 
MOVE. W D3,CensusRec .extentCountCA4) ;Report extent count 
MOVE.W ®noErr ,00 Nothing is wrong 
RTS ; Bye-bye 


ENDPROC 


9 
; This routine is called Бу the client to write data to the 
; driver 
DriverWriteData PROC 
IMPORT F indExtentByDandHC 


WriteRec RECORD 0 
Func 05.41 
docID DS.L 1 
hatCheck DS.W 1 
edition DS.W 1 
formatCountDS.W 1 
theData DS.L 1 
WriteRecSize EQU * 
ENDR 


FmtDataBlock RECORD 
formatCode DS.L 1 
dataSize DS.L 1 
myData DS.L 1 

ENDR 


MOVEA.L (A6),A2 ;Dereference globals handle 
MOVE.L WriteRec.docIDCA4),D8  ;Get the passed docID 
MOVE.W WriteRec.hatCheck(A4),D1;Get the passed hatCheck 
JSR FindExtentByDandHC ;Get dependancy if it 

exists 
BEQ.S TableSetup ;Get going. Otherwise, 
RTS ;Subr plotzed..leave w/o popping Al 


Тар1е5е (ир 
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MOVEA.L (А62,А2 ;Dereference globals handle 

LEA IACGlobals.ExtentTableCA2),A2;Get table base 

MOVE .W WriteRec.formatCount(A42,D5 ;Get the passed 
formatCount 

EXT.L D5 

ASL.L 82/05 Мәке it an offset 

MOVE.L A1,-CSP) ¿preserve dCtlStorage Ptr 

MOVEA.L WriteRec.theDataCA42,A1 ;Get the passed 
theData 

MOVEA.L A1,A0 

-HLock ;Freeze the user data 

MOVEA.L СА1),А1 ;.And put the pointer in A1 


MOVE.L EditionHdr .EditionSize,DO ;How much global space 
do we want? 
ADD.L 05,00 ; Add format entries 
-NewHandle sys,clear;Try to allocate it (sys 
temporary? 
BNE WriteDataFai led ; .Couldn^t 
MOVE.L A0,07 ;ургезегуе 


MOVEA.L (Аб), А2 ;Dereference globals handle 
LEA IACGlobals.ExtentTableCA2),A2;Get table base 

with  ExtentRec 

ADDQ.W * 1,EditionC(A2,D2.L)  ;Bump edition 8 

MOVEA.L EditionListCA2,D2.L2,A3 ;Get handle to new 


chain head 
MOVE.L A0,EditionListCA2,D2.L) ¿Point to new head of 
chain 
MOVE.L MstrInterestMsk(A2,D2.L),D6 ;Need to copy into 
editionHdr 


endwith ;ExtentRec 

MOVEA.L 07,А0 ;Retrieve editionHdr handle 

MOVEA.L (Аб), Аб ¿Hook list after new block 

MOVE.L AS,EditionHdr .NextEdCA0) ;Set EditionList->next 

MOVE.L D6,EditionHdr.InterestMaskCA2) ;Remember who's 

interested 

MOVE.W WriteRec.formatCount(A4),D6 ;Get the passed 
formatCount 

MOVE .W D6,EditionHdr .NumFormatsCA2) ;set format count 

MOVEA.L 07,А0 

-HLock ;Freeze new block 

MOVEA.L (А0),АЗ ;Deref it.. 


OncePerFormat 


SUBI.W 84,05 ;Knock down the format offset 

MOVE.L FmtDataBlock .dataSizeCA1),D8 ;Get this block’s 
size 

¿Add room for the fmtcode 

MOVE.L 00,06 бес up count 

SUBQ.L #1,D6 ; Adjust for DBRA 

-NewHandle sys,clear ‚Тгу to allocate it 

BNE.S WriteDataFailed ; Couldn't 


ADDI.L 84,00 


MOVE.L Аб, 06 
MOVE.L A1,D7 
MOVEA.L (Аб), Аб 
with FmtDataBlock 

MOVE.L dataSizeCA12,D0 ;Get this block's size 
MOVE.L formatCode(A12,CA0)* ;Copy the format code 
MOVEA.L А0,А1 ебі pointer for BlockMove 
MOVEA.L 07,А0 ;Source pointer for BlockMove 
ADDA.L *8,A0 ;Skip hdr info 

-BlockMove 

MOVE.L 07,А1 

MOVE.L dataSizeCA12,D0 
endwith ;FntDataBlock 
ADDQ.L 88,00 ;Allow for header 

ADD.L 00,41 X ;Reset А1 to next format block 

MOVE.L 06,А0 (бей handle to ТАС data copy 

MOVE.L A®,EditionHdr .EdInstances(A3,D5.L) ;Record handle in 


;Зауе handle to IAC data copy 
;Зауе ptr to user data 
;Deref the IAC copy block 


бей this block’s size 


EditionList 


TST.L 05 ¿Are we done? 
BNE.S OncePerFormat о it again.. 
MOVEA.L WriteRec.theData(A42,A0  ;Get the passed 
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theData 

HUn lock jAnd unlock this puppy too 

MOVE .L ExtentRec .EditionCA2,D2.L ),04 

MOVE.L D4,WriteRec.editionCA4) Update the edition 

MOVE.W ЗпоЕгг,00 jWe’re copacetic at this 

point 

WriteDataExit 

MOVEA.L (SP)+,A1 

RTS ; Bye-bye 
WriteDataFai led 

MOVE .W *WriteFailed, DØ 250 solly 

BRA.S WriteDataExit 


¿restore dCtlStorage 


ENDPROC 


; This routine is called by client to read data from the 
driver 


Dr iverReadData PROC 
IMPORT F indExtentByDandHC, IsFormatAvai lable 


ReadRec RECORD 0 
Func 058.0 1 
docID DS.L 1 
slotID DS.W1 
hatCheck DS.W 1 
edition DS.W 1 
formatPref DS.L3 
formatCode DS.L 1 
theData DS.L 1 
ReadRecSizeEQU * 
ENDR 


MOVEA.L (А62,А2 дегеГегепсе globals handle 
MOVE.L КеасКес. бос10(А42,00  ;Get the passed docID 


MOVE.W ReadRec.hatCheck(A42,D1  ;Get the passed hatCheck 


JSR FindExtentByDandHC 
BNE ReadDateExit 
MOVEA.L (A6),A2 ;Dereference globals handle 

LEA IACGlobals.ExtentTableCA2),A3;Get table base 

MOVE .W ExtentRec.EditionCA3,02.L),D4;Fetch latest stored 


бей dependancy if it exists 


edition 
CMPI.W #-1,04 ;If edition not -1 
BNE.S LinkStillValid ;,.Link is OK 


MOVE.W ®MissingL ink, 00 

BRA ReadDataExit 
LinkStillValid 

CMP.W ReadRec.edition(A4),D4  ;Has he seen my latest? 

BLE.S FetchLatestEdition 

MOVE.W 8NoNewerEdi tion, 00 

BRA ReadDataExit 
FetchLatestEdition 


;„Е1ѕе link was invalidated 
;бо bye-bye 


Уез, he has.. 


MOVEA.L ExtentRec.EditionListCA3,D2.L2, A0 ; The handle for 


latest ed’n 
MOVEA.L (А0),АЗ АЗ -› latest ed’n 
-HLock ;Freeze this puppy 
LEA ReadRec.formatPrefCA4),A2 ;Point to first format 
JSR IsFormatAvaileble ;15 format 1 ok? 
BNE.S RenderMe 216 so, render it.. 
(ҒА 4(A2),A2 ¿Point to second format 
TST.W (A2) ;If no format 2.. 
BEQ ReadDataFai led 
JSR IsFormatAvailable ;Is format 2 ok? 
BNE.S RenderMe ИЕ so, render it.. 
(ҒА 4СА2), А2 ¿Point to third format 
TST.W (A2) 2ІҒ no format 3.. 
BEQ ReadDataFai led 
JSR IsFormatAvailable ;Is format 3 ok? 
BEQ ReadDataFai led ;If not, bail out.. 
RenderMe 
MOVE.L (A2),ReadRec.formatCode(A4) ;Set format code 
MOVEA.L САб), А2 ;Dereference globals handle 
(ҒА IACGlobals.ExtentTableCA2),A2;Get table base 
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;If subr plotzed get out. Otherwise, 


MOVEA.L ExtentRec.EditionListCA2,D2.L2,A0 ; The handle Гог 
latest ed'n 

MOVE.L Аб, -CSP) ¿Save for later 

-HUn lock ¿Dismiss it 

MOVE.L 07,А0 ;,Put render handle in Ай 

-GetHandleSize ¿How big are we? 

SUBQ.L 84/00 ;Fudge size param for type code 

MOVE .L 00,06 Save size param 

-HLock ;Freeze the EdInstance 

MOVEA.L (Аб), АЗ ;Deref it 

MOVEA.L ReadRec.theDataCA4),AB  ;Get output handle 

MOVE .L 06,00 ¿Get real size 

-SetHandleSize Мәке enough гооп... 

MOVE.L A1,-CSP) ¿Stack dCtlEntry 

MOVEA.L (А0),А1 ;Destination 

LEA 4(АЗ),А0 ;Source starts after formatCode 

MOVE .L 06,00 ;Reload real size 

-BlockMove 

MOVE.L CSP)+,A1 


;Retrieve dCtlEntry 
MOVE.L 07,А0 


;Put render handle in Аб 


HUn lock Дес it go 
: Now delete edition if no further interest 
KillEditionLoop 

TST.L (SP) ;Valid address? 


BEQ.S ReadData0K 
MOVEA.L (5Р2,А0 

MOVEA.L (А02,АЗ 

with  EditionHdr 
MOVE.L InterestMask(A3),D5 ;Get interest mask 

MOVE.W ReadRec.slotIDCA4),D8 — ;Get bit position 
BCLR.L 00,05 ;Cleer interest bit 

MOVE.L D5, InterestMaskC(A3) ;Save updated mask 

BNE.S ReadDataOK ;Still interested parties, keep data 
MOVE.W NumFormatsCA32,D7  ;Loop limit 

SUBQ.W 81,07 ¿Set up for DBRA 

LEA EdInstances(A3),A2 ;Point to base of table 
endwith ;EditionHdr 


Exit if not.. 
¿Reload handle to edition header 
АЗ -> latest ed’n 


Killloop 
MOVEA.L (422,40 Handle to data 
-DisposHandle Kill it 
LEA 4(А2),А2 ¿Next entru 


DBRAD7,KillLoop 

MOVE.L EditionHdr .NextEdCA3),D5 ;Save Link 

MOVEA.L (5Р),А0 ;Reload header handle 
-DisposHendle Kil] it 

MOVE.L D5, CSP) ;Replace handle with link 

BRA.S KillEditionLoop ; Try removing earlier edition 


ReadData0K 
MOVEA.L (462,42 ;Dereference globals handle 
(ҒА IACGlobals.ExtentTableCA2),A2;Get table base 
MOVE.L (SP)+,ExtentRec.EditionListCA2,D2.L) ;Relink 
handle for latest ed'n 
MOVE.W 80/00 
ReadDataExit 
RTS 


; Indicate exit OK 


ReadDataFai led 
MOVE .W ®ReadFai led, 00 380 solly 
BRA.S ReadDataExit 


ENDPROC 


; Unused entry points that must be defined for the header’s 
jump table 


DriverCtl PROC 
EXPORT Dr iverDone 
DriverDone 
MOVEQ &0,00 ;Everything/s cool 
RTS ;Return to sender 
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ENDPROC 


¿Manu uears later...the Subroutines!! 


¿Returns DØ.W = slot ID 
; A3,D1.W pointing to available entru in docID list 
FindSlotID PROC 
MOVEA.L (A6),A2 ;Dereference global handle 
LEA IACGlobals.docIDsCA22,A3 ;Point to list of docIDs 
MOVEQ #-4,01 ¿Starting index of zero 
MOVEQ %0,03 ;Starting slot ID 


SlotIDLoop 
ADD.W 84,01 ;Bump to next index 
ADD.W 81,03 ;Bump counter 


CMP.W #NumOfDocs+1,D3 

BEQ.S SlotIDFail 

CMP.L (A3,D1.W2,D0 

BEQ.S StuffSlotID 

TST.L CA3,D1.W) 

BNE.S SlotIDLoop 
StuffSlotID 

MOVE.W 03,00 
SlotExit 

TST.W 00 

RTS ;Return to sender 
SlotIDFai1 

MOVE.W ЗМоМоге510%5,00 

BRA.S SlotExit 


‚Аге we done yet? 
;If so, we can’t create slot ID 
;Compare it to our docID 
;Exit if we're done 
¿See if open slot 
¿If not, try again 


,Move to result register 


¿Custom OSErr 


ENDPROC 


) 

¿Looks for дер іп extent table by matching docID and hatCheck 
;ASSUMES THE FOLLOWING 

; DØ = docID 

; 01 = hatCheck 

; A6 = globals handle [always] 

; RETURNS 

; 00 = noErr OR NoSuchDep 

; 02 = desired offset 

¿We merrily destroy А2 and АЗ during this routine 


FindExtentByDandHC PROC 
MOVEA.L (462,42 
LEA IACGlobals.DocIDs(A22,A3 ;Point past end 
LEA IACGlobals.ExtentTableCA2),A2;Point to extent table 
MOVEQ #0,D2 ;Clear our offset 
FEBDAHCLoop 
CMP.L ExtentRec.docIDCA22,D0 ;Check this extent’s docID 
BNE.S SkipToNextExtent ¿If wrong, skip to next 
CMP.W ExtentRec.hatCheck(A2),D1 ;Check this extent’s docID 
BNE.S SkipToNextExtent ;If wrong, skip to next 
MOVE.W ЯпоЕгг , Dd ¿Nothing is wrong 
BRA.S FEBDAHCExit бей out. 


SkipToNextExtent 
ADD.L *ExtentRec.ExtentSize,D2 ;Bump offset 
ADDA.L ExtentRec.ExtentSize, A2 ;Point to next record 
CMPA.L A2,A3 ; Are we done? 
BGT.S FEBDAHCLoop ;If not, look again 


FEBDAHCFai1 


MOVE.W ЗМобусһбер,00 ;Return custom OSErr 


FEBDAHCEx i t 
. TST.W DØ 
RTS ;Вуе-Буе 


ENDPROC 


¿This routine wipes out all data апа formats thereof for a 
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single extent 
; ASSUMES 
; Аб = current EditionList 
Ме merrily destroy АЗ,00, апд 05 (А2 restored from A6) 
; RETURNS 
; Nothing in particular 
WipeExtentData PROC 
with IACGlobals 
with ExtentRec 


MOVE.L А0,00 
BEQ.S DoneExtent 
MOVEA.L 00,АЗ 


¿Test handle to Edition List 
If none, do nothing 
¿Keep Edition List handle 


NextEdition 
MOVEA.L АЗ, АО ;Get Edition List handle 
-HLock ;Lock the Edition List handle 


MOVEA.L (АЗ), АО ;Get pointer to Edition List 
with EditionHdr 

LEA EdInstaencesCA22,A2 ;Point to instance data 
MOVE .W NumFormats(A@),05 ;Get counter of formats 


KillFormat 
MOVEA.L (422,40 ;Get the handle to the data 
-DisposHandle ;Get rid of it 


(ҒА 4(А2),А2 
SUBQ.W 81,05 
BNE.S KillFormat 


;Point to next instance 
;Decrement the counter 
¿And do it again 


МОМЕА. (A32,A0 
MOVE.L NextEd(Ag), 05 
MOVEA.L АЗ, Аб 


;Dereference the Edition List handle 
бей handle to next Edition 
;Restore handle 


-HUn lock ,Unlock it 
-DisposHandle ;Get rid of it 
TST.L 05 416 there a next Edition? 


BEQ.S DoneExtent 
MOVEA.L 05,АЗ 


¿If not, go to next extent 
;Otherwise move the handle 


BRA.S NextEdition  ;And loop 

endwith ;EditionHdr 

endwith ;ExtentRec 

endwith ; IACGlobals 
DoneExtent 

MOVEA.L (А62,А2 ;Restore 

RTS 

ENDPROC 


¿Looks for ап dep in the extent table by matching the docID 
end hatCheck 

J ASSUMES THE FOLLOWING 

; А2 = pointer to formatCinteger) 

; АЗ = pointer to Edition record 

; RETURNS 

; 07 = NIL OR handle to EdInstance 

Ме do not touch A2,A4 during this routine 

¿We merrily destroy А0,04,05 during this routine 


IsFormatAvailable PROC 
MOVE .W EditionHdr .NumFormatsCA3),D5 ;Get number of 
formats availeble 
MOVE.L (А2),04 ;Hold desired fmt code 
SUBI.W 81,05 
LSL.W #2,05 
MOVE.L 80,07 
FormatCheck 
BLT.S FormatCheckDone 05 is now zero 
MOVEA.L EditionHdr.EdInstences(A3,D5 .W), Ad ¿Move 
handle to EdInstance 
MOVE.L А0,07 ;Save in case it’s good 
MOVEA.L (Аб), АО ;Deref 


¿Make it an offset 
бес return to NIL 
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CMP.L САЙ),04 

ВЕ0.5 FormatCheckDone 

SUBI.W 14,05 

BRA.S FormatCheck 
FormatCheckDone 

TST.L 07 

RTS 


¿Are the formats the same?? 
If so, leave 
¿Check next one back.. 


;Set the condition code first 


ENDPROC 
END 


Listing SAWSINIT.a 


QEOOOOCODOODCEEPODUODCODCDCDDODOODODCOIOODOODORDOOROCEIOOREEIOECEGIOOEXEEXGE 
,*****The SAWS Inter-Application Communication Driver Loader 
,*****Written with blazing speed 6-7/88 by Paul F. Snively 
;***** With one HELL of a lotta help from Frank Alviani 


; ЖЖЖЖЖЖ ЖЖ ЖЕ ЖЕ ХК К КК ЖЖ ЖЖ 


7 

¿Modification History: 

;6/19/88 First Draft-Paul F. Snivelu 

31/18/88 Hopefully last draf t-this SHOULD work- 

¿Paul F. Snively 

;8/21/88 Now searches for open slot from end of table- 
¿Frank Alviani 

; CAlgorithm from Pete Helme, Apple MACDTS) 


д 

;Basically what this puppy does is to assume that there's а 
;DRVR resource lying around that happens to be named *.IAC" 
запа, if there is, it loads it into the 

;System Heap and opens it. Simple, huh? 


2 


INCLUDE 
INCLUDE 


‘Тгарз.а’ 
‘QuickEqu.a’ 
INCLUDE ‘SysEqu.a’ 
INCLUDE ‘ToolEqu.a’ 
; STRING ASIS 


successID EQU 128 
failureID EQU 129 


SAWSINIT: PROC 
IMPORT Show INIT 


Frame RECORD 4,DECR 
return 05.1 1 

A6L ink 05.1 1 

theID DS.W 1 
theType 05.1 1 

name 05.8 256 

fSize EQU * 

ENDR 


LINK Аб, Frame .f Size ;space for locals... 

Find an open slot in the driver table and load into that 
MOVE М UnitNtryCnt, 02 ;How many slots? 

SUBQ.W 81,02 j Adjust 

MOVE.W 02,01 ;Set up offset 


we 


LSL.W 82/01 

MOVEA.L UTableBase, Аб Мһеге”5 the table? 
SrchLoop 

TST.L 0CA0,D1.W) ¿Available? 

BEQ.S GotSlot ¿Yup... 

SUBQ.L #4,D1 ¿Drop Offset 


SUBQ.W 81,02 

CMPI.L 839,02 

BGT.S SrchLoop 

BRA.S BadNews Мо open slots in the inn 
бес resource by name 
GotSlot 

SUBQ.W 84 А7 


¿Drop slot ID 
; M bottom limit? 


;space for handle 
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MOVE .L #$44525652,-(АТ) ; DRVR’ 
PEA DriverName 

_GetNamedResource 

MOVE .W ResErr ‚00 бес it? 


BNE.S BadNews 

MOVE.L (А72%,07 

BEQ.S BadNews 
;Change ID to open slot 

MOVE.L 07,-CA7) 

PEA Frame.theIDCA6) ; ID 


¿Was there enough memory? 


РЕА Freme.theTypeCA6) ;theType 
РЕА Frame.nameCA6) ¿name 
-GetResInfo 
MOVE.L D7,-CA7T) 
MOVE.W D2,-CA7) 
РЕА Frame.nameCA6) ¿name 
—SetResInfo 

;Ореп the driver! 
CLR.W -(AT) ;Room for refnum 
PEA DriverName ;Point to driver name 
-OpenDeskAcc ;Open it 


MOVE.W CA7)+,D1 ;Pop refnum 
;Ensure Driver undisturbed 
MOVE.L 07, -САТ) 
-DetachResource 
;Restore previous slot in file 
MOVE.L #$44525652,-(АТ) ; DRVR’ 
PEA DriverName 
_бе{МатедКезоигсе 
MOVE.L 07,-(АТ7) 
MOVE.W Frame.theIDCA62,D0 
MOVE .W 00,-САТ) 
MOVE.L 80 – САТ) 
—SetResInfo 
MOVE .W *'successID, -(SP) 
ShowICON: 
MOVE.W #-1,-(5Р) ,Use standard pixel offset 
MOVE.L (SP)+,DØ — ;TEMPORARY! POP OFF PARMS 
; JSR ShowINIT ;Tell user that driver installed 
UNLK A6 


;leave alone name 


;Stack success 1С№ ID 


RTS ¿And that’s all, folks! 
BadNews: 
MOVE .W *failureID,-CSP) ¿Tell user we failed 
miserably 
ВКА.$ ShowICON ;And leave 
Ог iverName : 
DC.B’. IAC’ ; The name of our driver 
ENDPROC 
END 


Listing SAWSINIT.r 


/*The Resource Description File for the IAC Driver 
Frenk Alviani - 8/88 
х / 


include $$ShellC^hlxEtc^) “SAWSdrvr.lnk? 'DRVR^ (31) 
аз ‘DRVR’ (31,^. IAC’, sysheap, nonpurgeeble?; 

DRVR resource */ 

include $$ShellC^hlxEtc^) “SAWSINIT/; 

7 


/* get 


/* get INIT resource 


/* ICN® s will go here asap */ 
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С Workshop 
MenuStuff for Handling Menus 


MenuStuff 

Menus are an essential part of the Macintosh interface, and 
the resource formats for creating menus and the ToolBox rou- 
tines for implementing them and reacting to user choices are 
some of the most straight forward areas of Macintosh program- 
ming. But menus have two faces : the logical aspect, and what I 
will call the “housekeeping” aspect. Reacting to choice i,j by se- 
lecting font F is an example of the logical aspect; knowing that 
item j in menu i must be checked when chosen and that items j- 
m..j-1 and items j+1..j+n must be unchecked (to say nothing of 
the repercussions this might have on the display characteristics 
of Font Size Menu Z) is an example of the housekeeping aspect. 
This latter aspect is neither conceptually difficult nor algorithmi- 
cally rewarding, but it generates an awful lot of extra code which 
is essentially similar from one program to another yet usually 
sufficiently program-specific that the routines end up being 
rewritten every time. Furthermore, the algorithmic triteness 
creates a paradox : programmer disinterest invites bugs, and it is 
usually late in the development cycle before these “visual feed- 
back" features work correctly, whereas more difficult parts of the 
program, by capturing the programmer’s interest, frequently are 
bug-free (sic) much earlier. 

My solution to this problem(contrary to Beethoven, if you 
will excuse the presumption, I hate writing variations!), has been 
to: 


1) list the different ways menu items behave and extract 
common types, 


2) devise a custom resource format that codes the menu’s 
“housekeeping” behavior; this custom resource complements 
(without modifying or replacing) the standard menu resource, 


3) write a set of routines which, driven by the custom 
resource, carry out all housekeeping activities for the application 
program in a completely transparent manner, i.e., the program 
needs only call the front end after MenuSelect and then carry out 
the logical aspects of choice ij in blissful ignorance of the 
mechanico-visual aspects of the User choice. 


Obviously my menu types are not exhaustive. It seems that 
almostevery new program that hits the market finds a new variant 
on the menu theme. Nevertheless the basic types are covered and 
new types are easy to create. The types work equally well 
whether the menu be straight pull-down, hierarchical, or pop-up 
(and presumably tear-off); dynamic item addition/suppression 
are supported (though with certain restrictions on the types); a 
mechanism is provided for storing/restoring a snapshot of a given 
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menu state; dynamically allocated zones containing runtime 
information can be resource-triggered; and finally PROC type 
resources can be associated with menus and transparently exe- 
cuted on menu selection, thereby providing a mechanism for 
interactions between menus. | 

Excuse the drum-beating : it's really quite straightforward. 
There are no neat ToolBox tricks to be learned from this article, 
its only purpose is to relieve you of some of the drudge-work of 
menu handling. 

The sources in this article are written in Consulair Mac C 
(having started it a long time ago, I updated in Mac C; it will be 
last thing I write in Mac C). Adapting it to the C language of your 
choice should be easy, insofar as no specific features are used 
(other than 32 bit int's). 

Just as menu housekeeping in an application program takes 
up an amount of space disproportionate to its conceptual interest, 
50 these routines are rather long. In order to fit it into the space 
graciously allotted by the Editor (let us not dwell on his displeas- 
ure with the original size), I had to cut out quite a bit of code, and 
compact the remaining code to the detriment of its legibility. The 
Source available with this issue contains the full length code 
along with a very thorough test program that allows complete 
testing of menus before integrating them into the final applica- 
tion. This is very important, because the custom nature of the 
resource makes coding it very error-prone, and the source code 
presented has had the data-validation part amputated and the 
error reporting routine severely watered down. In the perfect 
leisure world of my fantasy, rather than using RMaker to create 
the custom resource it would be generated by an interactive 
utility. 


Name Calling 
Not surprisingly, the key data structure is called MenuStuff, 
and this structure will be referred to as MS (that these also happen 
to be my initials is of course pure coincidence). Its complete 
description may be found in “MS.h”. 


Item Types 
The basic item types recognized by MS routines are the 
following : 


1) Normal : straight-Joe items requiring no special process- 
ing. 


2) Check Toggled : an individual item which is either 
checked or not checked, and toggles between these states with 
each successive selection. Example : Gremlin Alert in QUED. 
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3) Text Toggled : an individual item whose text exists in two 
variants; successive selections toggle the display of these alter- 
native text variants. Example : a Hide/Show item. 


4) Enabled Pair : a pair of menu items one of which one is 
enabled and the other disabled at any given time. Selecting the 
enabled member disables the selected member and enables the 
other member of the pair. Example : Open/Close items in 
MacWrite. 


5) Checked Range : a set of items for which one and only опе 
element must be checked at any given time. Example: a Font Size 
menu. 


6) Cumulative Range with Reset : a set of items with one 
singular element (the parent) and one or more non-singular 
elements (members); at any given time at least one element must 
be checked. Several members may be concurrently checked, but 
the parent and members are never checked concurrently; select- 
ing a member unchecks the parent, and unchecking the last 
checked member checks the parent (no, this is not a chess journal, 
you did pick up the right magazine). Individually, members 
behave like check toggled items. Archetypical example : the 
Style Menu. 


7) Enabled Set : a set of items comprised of two disjoint 
subsets. Each subset contains a singular element (the parent) and 
one or more non-singular elements (members); at any given time 
all elements of one of the disjoint subsets are enabled and all 
members of the other subset are disabled. Selecting the enabled 
parent of the enabled subset disables all elements of the selected 
subset and enables all elements of the other disjoint subset. 
Individually, the member elements behave like normal items. 


8) Text Toggled Set: aset of items with one singular element 
(the parent) and one or more non-singular elements (members); 
each element’s display text exists in two variants, and successive 
selections of the parent toggle the display of these alternative text 
variants for all elements in the set. Variant display is coherent, i.e, 
at any given time the same variant level is displayed by all 
elements of the set. Individually, member elements behave like 
normal types. 


9) Disabled Menu Lines : self-explanatory; used to “parse” 
set membership when set membership is defaulted in the MS 
resource, otherwise ignored by MS routines (more on this point 
later). 


Iam not trying to dictate menu behavior, I am describing the 
predefined types this version of MS knows how to handle. Any 
type of behavior differing from the predefined types may either 
be tagged as Normal (hence ignored by MS routines and fielded 
by the application), or else new types may be added to the MS 
routines. 


Functional Overview 
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Menu creation per se is totally independent of MS. Once 
menus are created, if the menu contains items the programmer 
wants MS routines to handle, a complementary MS resource 
must be created using R Maker or equivalent. At this point linking 
the test program (MST.Rel) with the menu and MS resources will 
immediately show not only what the menus look like, but also 
how they react to user choices. Not a line of application code has 
so far been written, yet the menu interface is a faithful presage of 
the real thing. 

In the application, a call to MSMake should be followed by 
a call to MSInsert. Then, in the doMenu section of the applica- 
tion, before the Menu/ItemNumber Switch, a call to MSDispatch 
should be inserted. To delete a menu from the MenuBar without 
disposing of memory structures (both standard and MS), the 
application should call the ToolBox DeleteMenu routine. To 
dispose of associated memory structures (again, both standard 
and MS) the application should call MSDispose. To add/delete 
items to/from existing menus MSInsMenultem/MSDelMenu- 
Item should be called. See below for snapshots and inter-menu 
interactions. 

In its present form MS routines do not act on MenuBars, but 
adding a front end to MSMake, MSInsert, and MSDispose is 
trivial. Actually MS itself is trivial, and the the point of this whole 
article is to prove the usefulness of coordinated triteness. 


Underlying Mechanics 

More on name calling : up until now I have used MS for 
MenuStuff and consistently qualified it with either “routines” ог 
“resources”. The main MS resources type is ‘MST “ (MST 
blank); therefore I will henceforth use MST to designate the 
resource and MS to generically designate MS routines. 

MST is a non-purgeable, variable length resource that MS 
never rewrites to disk. As you will see shortly, menu states can 
be faithfully memorized and restored using a small, masked flag 
structure. MST is composed of constant header fields affecting 
the entire menu, a variable size Menu Verb Table (MVT) coding 
behavior at the item level, and an optional ‘PROC’ function 
parameter zone following the MVT (more on this later). 

Each MVT entry is a MenuVerb structure, composed of an 
opCode component and a 5-element argument table (argT) 
component. OpCodes and argTs are typedef'ed to byte, which is 
adequate for the predefined types but may be changed if longer 
argTs should be necessary for new types. MVT[O] contains bit 
flags (referred to as Menu Flags) which affect the way menus are 
setup by MSMake, and govern certain aspects of PROC function 
behavior. The opCode identifies the item type, and the argTs 
supply positional information necessary to implement the type's 
behavior. Notall types use all the argTs, and argT[4] (the last one) 
is never used by any predefined type; it pads to word length 
boundary, and may be used for new types, or itcan hold any item 
information the calling application might wish to store there. In 
general, argT[0] through argT[4] correspond to “first”, “last”, 
“parent” and “other” positional parameters, but in the case of 
TextToggled items, for example, “other” (argT[4]) is the index of 
the first text variant in the associated STR# resource (the second 
variant is other+1). These positional arguments may be ex- 
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pressed either as absolute itemNumbers or may be calculated by 
MS based on the previous and the next disabled line positions in 
the menu. Using direct references allows interspersing different 
members of a given group anywhere in the menu (as long as there 
are no intervening types with the same opCode), whereas using 
disabled line defaulting makes coding the resources a lot easier. 
A concrete example : for an Enabled Set, first and last are the 
position of the first and last element of THIS disjoint set, parent 
is the master item controlling THIS disjoint set's enabling/ 
disabling, and other is the itemNumber of the OTHER disjoint 
set's parent. 

Another essential part of the MST resource is the Tog- 
gleFlag component (not to be confused with the menu flags in 
MVTY[0]). In the present version ToggleFlag is typedef'ed to 
MenuVerb, giving a 48 bit field, but this can be increased to 
handle more items (but have mercy on the poor User!). Every 
timean item different from Normal or Disabled Line is passed to 
MSDispatch, the associated flag is toggled from its previous 
state. This new value determines the transition processing. For 
example, toggling a text toggled item causes the 
other ToggleFlag[i] variant to be displayed. Certain transitions, 
suchasa1-200naChecked Range are notallowed and the toggle 
flag is reset to its original value (otherwise there would be no 
checked member in the range). With one exception (Expanded 
Ranges, see below), the initial state of ToggleFlags must be 
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CORRECTLY coded into the resource; bits are numbered from 
left to right to allow for compatibility should ToggleFlags need 
to be lengthened. Bit zero is not used. 

Menu flags, occupying the first MVT entry, control the 
overall set up of the menu. There is a flag indicating if AddRes- 
Menu should be called, and if it is set, the field sysRes in the 
constant header should contain a resource type. Since the number 
ofresource items cannot be determined at resource creation time, 
itis impossible to code МУТ entries for these items. To solve this 
problem, another flag enables MVT expansion, and yet another 
enables ToggleFlag set up and initial menu checking. In the 
present version only Checked Ranges may be expanded using 
this mechanism, and this is adequate for most applications. Two 
fields in the constant header govern this expansion : staticCount 
and allocCount. StaticCount is the itemNumber of the last MVT 
explicitly coded, and allocCount is the total number of entries 
allocated in the MVT. Entries beyond staticCount should be 
codedas 6 zero bytes. After the resource is added, the staticCount 
entry is copied from the staticCount to the dynamicCount- 
staticCount last entries (dynamicCount is determined by a 
CountMItem call). If the number of added items should exceed 
allocCount, the menu is trimmed to allocCount. A flag indicating 
whether the user should be warned of this trimming is set aside 
but the warning is not implemented in this version. Increasing the 
maximum toggle flag "addressing" capacity only adds 1 bit of 
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[unused [unused ^ [unused [unused ^ | Not toggled. not processed: : 
unused | IT 
default STR# Indx (if 


— | MSMake 


ЕН ие иена _ 
zero->NEXT,<zero->PREV | 0-> Disable this item, Enable other item. 
for Exp Rng, # of member 
to be initially checked 


(defaults to 1 or MIVT 


other Set parent, 
defaults to : zero->first of 

NEXT line grp, «zero-»first 
of PREV line grp; 
default STR# Indx (if 
NULL, patched by 


¢1-> Chk, 0->Unchk. 
‘Display STR# string indexed by 


(other TogFlg). 


°1->Chk, unchk other mbrs 
0->Not allowed. 


ememb: 1->chk, if parent chked unchk prnt; 
O->unchk, if no other mbr chked chk prnt ; 
parent: 1->chk prnt; unchk mbrs; 
0->retoggled. 
emember: retoggled; 
parent : 1->ignored; 

0->disable this set,enable other set; 


«member : retoggled; 
parent: group display text set to STR# 
string indexed Бу (other TogFlg) 
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overhead per item, so it is easy to allow for lots of fonts, or 
whatever other resources the application needs. Only the size of 
menus actually concerned with this resource will be increased 
beyond this 1 bit overhead. 

The Expanded Check Range mechanism, though strictly 
necessary only for resource additions, can also be used to expand 
any Checked Range. The staticCount entry must have a Check 
Range opCode, and if the first argT is less than or equal to zero, 
the StaticCount entry will be copied into the dynamicCount- 
staticCount last entries, as explained above, and the “first” argT 
will be set to staticCount and the “last” argT will be set to 
dynamicCount. If however, the first argT is different from zero, 
the staticCount entry will still be copied, but from “first” to "last" 
only, without modification. 

There are three ways to specify which entry in the Expanded 
Range should initially be checked and have its toggle flag set : 


• argT[4] (“other”) is not normally used in Checked Range 
types; if the Expanded Range flag is set, however, and this argT 
is non-zero, it will be interpreted as the default item relative to 
staticCount, e.g., 3 would mean StaticCount + 2, 


• if this argT is zero, then if the MST has an associated MIVT 
(Menu Item Value Table), and if the table contains an entry 
whose value is equal to the MIVTdefVal field, then the position 
of this value in the table gives the item to be checked, 


• if these schemes fail, item number staticCount is checked 
and set. 


Special Features 

In order for the application to dynamically add items to an 
installed MST menu, extra space must follow the staticCount 
entry in the MVT, i.e, staticCount must be strictly less than 
allocCount, and as items are added/deleted, dynamicCount must 
never exceed allocCount. Notice that MSInsMenultem does not 
exit via MSErrExit on error, it returns a negative error code 
instead. Items are added by passing a menuID, an item string 
pointer (which is passed directly directly to the ToolBox Ins- 
Menultem routine, so it may include metacharacters), an after 
and a MenuVerb parameter. If the after parameter is non-null, it 
is taken as relative to StaticCount-1, e.g., both zero and 1 give 
staticCount and 5 gives staticCount + 4; out of range values are 
clipped to either staticCount or dynamicCount. Normal return 
values give the absolute itemNumber of the added item. Toggle 
flags are not set and the menu is neither checked nor enabled as 
a result of calling MSInsMenultem, so the addition of singular 
elements should be followed by a call to MSDispatch, passing it 
the absolute itemNumber returned by MSInsMenultem. 
TextToggled and TextToggled Sets MAY NOT BE ADDED IN 
THE PRESENT VERSION. Different groups should either be 
separated by a disabled line insertion, or exact argT parameters 
MUST be supplied, though interesting effects can be obtained by 
mixing different types, so caveat emptor. 

The MIVT/PROC mechanisms are extremely useful. 
Though they can be used independently, they complement each 
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other and the dynamic menu addition mechanism to provide a 
powerful way of writing resource-driven processing that is 
independent of the main application. 

A menu flag governs the allocation of an MIVT (Menu Item 
Value Table). The table consists of allocCount- 1 longs allocated 
by NewHandle and initially set to MIVTnullVal. A handle to the 
table is stored in the MST. Another flag determines whether this 
table will be left alone or whether a PROC resource, whose ID is 
stored in procID[0], will be called to set it up. In either case a later 
call to MSGetMIVT, passing menuID and itemNumber, re- 
trieves the entry. 

A second PROC may be associated with the menu by storing 
its ID in procID[1]; this second PROC will automatically be 
calledevery time MSDispatch is entered. If the appropriate menu 
flag is set, the short integer following the MVT contains the 
number of shorts needed to store any additional parameters the 
second PROC might need to carry out its task (such as the ID of 
aor the secondary menus the selected menu might interact with). 

Using PROC parameters allows for reusable code. Appro- 
priate functions can be written and stored, and used by different 
applications. On the other hand, you do not have to use PROC 
functions. In addition to the blessed menuID, MSMake takes two 
additional parameters which will override the PROC IDs: they 
should be function addresses setup to receive the standard PROC 
parameters. These function addresses will be stored in the procID 
table of MST, and appropriate menu flags will be set by MS Make 
to indicate that the “PROC” functions are application functions 
and not really PROC resources. 

The test files included contain three sample PROCs. PROC 
ID 1 calculates the font IDs for installed fonts, and stores them in 
the Font menu MIVT. PROC ID 3 scans the text of the size menu 
and converts the first numeric sequence it finds to a long integer 
and stores it in the Size menu MIVT. PROC ID 2 is associated 
with the Font menu, and is called every time this menu is selected. 
It retrieves the font number for the selected item from the Font 
MIVT, gets the ID of the Size menu from the optional PROC 
parameters following the MVT, and then scans the Size menu 
entries, retrieving the font size from its MIVT. Any size entry that 
matches a RealFont gets its text outlined. The calling application 
is never aware of any of this visual processing, and simply 
retrieves font IDs and numeric sizes for logical actions associated 
with the menu choice without having to declare tables, make 
conversions, etc. 

The PROC mechanism and the dynamic menu addition 
features provide a convenient solution to the problem of display- 
ing open window titles in a menu, with the front window item 
typically checked. When the user chooses a window menu item, 
the corresponding window is brought to the front. This is a very 
common feature of most multiple window programs. 

Initially no windows are open, and no window items appear 
in the “Window” menu. When a window is opened, MSInsMenu- 
Item should be called, passing a menuID,a Checked Range type 
Menu Verb having zero first and last parameters (the staticCount 
item is assumed for convenience to be a disabled menu line), the 
Window Title string pointer, and either zero or a large number 
as the after parameter. Then the windowPtr should be stored in 
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the MIVT, in the entry whose index is the itemNumber returned 
by MSInsMenultem (the short version of MS presented here 
lacks the MSSetMIVT and MSFindMIVT functions, but they are 
easy to code, and are present in the longer version included in the 
source disquette). Nexta call to MSDispatch will check this item. 

When a window is closed, find its windowPtr in the MIVT, 
and the corresponding index is the itemNumber to delete by 
calling MSDelMenultem. 

The Toggle Flags provide the means by which menu states 
may be memorized throughout without ever changing the main 
MST diskresource. The MSAdjTog function takes a menuID and 
two ToggleFlag pointers as parameters. The first ToggleFlag 
pointer isa ToggleFlag, and the secondis a ToggleFlag mask. For 
every bit for which the corresponding mask bit is not zero, if the 
corresponding installed Toggle bit is different from the passed 
Toggle bit, MSDispatch is called for this item, effectively setting 
the menu to the snapshot state implicitly contained in the passed 
ToggleFlag/Mask pair. Processes whose states are reflected in 
menus need only store the appropriate masked toggle flags 
before deactivation, and call MSAdjTog passing this stored 
information when reactivated. 

A special resource, of type ‘MST1’, consists of just such a 
pair. These resources are optional, and their existence is deter- 
mined by the state of опе of the Menu Flags in MVT[0] (see 
above). When menusare originally setupby MSMake, if this flag 
is set , the ‘MST1’ resource will automatically be retrieved and 
MSAdjTog called. The application may update this resource and 
re-write it to disk by calling MSAdjPREV, which examines the 
mask contained in the appropriate *MST1' resource and updates 
the ToggleFlag part of the disk resource according to the value of 
installed Toggle bits. 


Extensions 

An easy extension would allow the application to set up but 
never insert a special MST menu the user would never see. This 
invisible menu would serve to code multiple menu interactions 
provoked by non-menu events (program choices, state changes, 
etc.). Code for new types would need to be included in MSDis- 
patch! & 2. These new types would never actually be accessed 
by User menu choices : the applications simulates MSDispatch 
calls on the dummy menu. The dummy menu may contain 
opCodes for which the argTs would be interpreted differently . 
For example, to implement a mass disabling, suppose new type 
for which : 


• [first] item number action applied to 

® [last] item number action applied to 

* [parent] is the singular element for the group 

° [other] is menuID to other alternate set (forces menuIDs to 
0-255, or need to change argT type to short) 

° [ (currently unused) argT[4] ] is the number of entries 
following this one. 


The MSDispatch code could be set for example to enable/ 
disable (depending on the dummy menus own toggle flag transi- 
tion), the specified range of the specified menu, for each item 
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verbin the list. Therefore a parenthetical call to MSDispatch with 
the dummy ij could trigger enabling/disabling over a multiple- 
menu set of items, independently of their primary MS coding. 

A far less obvious extension would be to develop an MST 
like structure controlling DITLs and other controls. Hmm... 

A better mousetrap ? 

Obviously for small programs using few menus, MS is 
shooting mice with elephant guns. For large programs, relying 
extensively on menus, MS offers a significant savings in pro- 
gramming time, it provides a way of rapidly visualizing the 
functioning menu interface, and may be easily adapted to provide 
for non-menu generated events having multiple-menu visual 
display repercussions. But is MST fun ? 

P m E 2 2: асы 
Listing: MS.h 


/*MS.h = metavariables and tupedefs for MS routines*/ 
tinclude “stdio.h” 

®include *MacDefs.h"^ 

®include "Resource .h"^ 

8include *Menu.h^ 

// MS.h = MenuStuff metavariebles 


Ме Verb Codes. ау 


"define .MVNORMAL 0 /* NORMAL ITEM */ 

#def ine .MVCHKTOG 1 /* CHECK TOGGLED */ 

8Sdefine _МУТЕХТОб 2 /* TEXT TOGGLED */ 

define .MVENABPR 3 /* ENABLED PAIR */ 

define .MVNZEXRG 4 /* NON ZERO EXCL RANGE "i 
#def ine .MVCMRGRS 5 /* CUMULATIVE RNG WITH RESET*/ 
"define  MVENBSET 6 /* ENABLED SET */ 

"define  MVTTGSET 7 /* TEXT TOGGLED SET */ 
"define  MVMENLIN -128 /* DISABLED LINE */ 
/* — Menu Flags ——— '— G— — 374 
#def ine . MFSYSLOD 0 /* LOAD SYSTEM RESOURCE x/ 
"define .MFERRTRM 1 /* ALERT USER TO TRIM х/ 
8#def ine .MFEXPRNG 2 /* EXPAND RANGE х/ 
8define .MFALOCTB 3 /* ALLOCATE MIVT TABLE х/ 
"define .MFBLDTAB 4 /* BUILD MIVT TABLE */ 
üdefine _МЕ$ЕТХЕб 5 /* SET EXP. RANGE TOGGLEFLG & 
MENU*/ 

Sdefine .MFSETPRE 6 /* SET TO PREVious STATE  */ 
#def ine .MFSUBMEN 7 /* IS А SUB-MENU жү 
8Üdefine  MFHASSTR 8 /* HAS TXTTOGSTR® RESOURCE */ 
8define .MFPRCPAR 9 /* PROC PARAMETERS FOLLOW MVT*/ 
"define _MFPRCFLG 14 /* USED INTERNALLY FOR PROC FUNCTS*/ 


/* — Resource Strings 2 }/ 


"define _MSMSTTYP ‘MST ” /* MENUSTUFF ТҮРЕ */ 
"define .MSSTRTYP ‘STR®’ /* TXTTOG STR" RESOURCE ТҮРЕ%/ 
def ine _МӘРЕСТҮР ‘PROC’ /* MIVT FUNCTION ТҮРЕ */ 


"define _MSPRVTYP ‘PREV’ /* RES FOR RESET TO PREV STATE*/ 


а peels x ые $) 
typedef char —MVOpCode; 

typedef char  MVArgT; 

"define _MVARGDIM 5 


typedef struct 
( MVOpCode opCode; 


MVArgT — argT( MVARGDIM]; 
) MenuVerb; 


typedef MenuVerb ToggleF lag; 
"define _ТЕВІТЅ2Е (sizeof (ToggleF lag)*8- 1) 


cee struct 
MenuHandle МН; 
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long sysRes; 

long **MIVTH; 
long ргос10121; 
long MIVTdef Val; 
long MIVTnullVal; 


short staticCount ; 
short allocCount; 
short beforeID; 


short ttgStrID; 

ToggleFlag TF; 

MenuVerb MVT(_TFBITSZE+1); 
)MenuStuff ; 
def ine -MSF IXLEN 42 
typedef MenuStuff X *MSPtr; 
typedef MSPtr *MSHd1; 


[* — —— Non- int Externals nn 
extern MSHd1 MSGe tMSHCO; 


Listing М.С 


/*MS.C = source code for MenuStuff Routines */ 
include “М5.һ” 


int MSMakeCmenuID, MIVTFct1,MIVTFct2) 


short menuID; 
int MIVTFct 1; 
int MIVIFct2; 
( /*Main Set Up routine - must be called before using menu*/ 


MSHd1 theMSH; 

MSPtr theMSP ; 

MenuVerb theMV, theMF; 

Handle theHdl; 

long def Val; 

int GJ 

short dunamCount,staticCount,allocCount; 
МУАГАТ defPos; 

MVOpCode opCode; 

short progNum=01; 


HLock((theMSH=MSGetMSH(menuID,progNum))); 
theMSP=*theMSH; 
theMF=*theMSP->MVT ; 
/* Get Menus */ 
if С! CtheMSP—MH-GetMenuCmenuID2) 2 
MSErrExitCprogNum, 22, nenuID, 2); 
/* Load System resources */ 
if (BitTstC&theMF, -МҒ5Ү51002) 
AddResMenu( theMSP-» MH , theMSP-? sysRes ); 
/* Trim to allocCount */ 
dynamCount=CountMI tems( theMSP-> MH); 
staticCount=theMSP->staticCount; 
a1 locCount=theMSP-> allocCount; 
while CdynamCount > allocCount) 
( DelMenuItenCtheMSP-»MH, dynamCount ); dynamCount-; ) 
/* Minimal validation */ 
if CstaticCount > allocCount) 
MSErrExitCprogNum, 18, menuID, 02; 
/* If TEXT TOG, check STR! & set Indx */ 
if (BitTstC&theMF, _MFHASSTR)) 
( if С! GetResource(_MSSTRTYP, theMSP-? ttgStrID) ) 
MSErrExitCprogNum, 07 , menuID, 0); 
E 
2-0; 
for (1=1;1 <= allocCount; i++) 
( opCode=theMSP-bMVT[i].opCode; 
if CopCode == .MVTEXTOG || opCode == .MVTTGSET) 
( if CtheMSP—MVTLil.argT(3] <= Ø) 
(theMSP-»MVT[il.argTI[3]2j*2*1; j**;) 
/* Set TXTOG items to TF state */ 
theMV .opCodez theMSP-»MVTI i ] .opCode; 
theMSP-»MVTLi 1. opCodez МҮТЕХТ00; 
MSTogBitCmenulD, i); 
MSDispatch 1( theMSP, menuID, i); 
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theMSP->MVT[i}.opCode=theMV . opCode; 


/* Expand Range for added resources */ 
if (BitTstC&theMF, _MFEXPRNG)) 
( theMVstheMSP-»MVT[staticCount 1; 
if CtheMV.opCode != _MVNZEXRG) 
MSErrExitCprogNum, 09, menuID, stat icCount?); 
if CtheMV.argT[0)] <= 0) 
(  theMV.ergT(O]-staticCount; 
theMV .argT( 1J-dynamCount; 
if CtheMV.argT(3]) 
theMV .argT(3]*-statícCount- 1; 


) 
for CistheMV.ergTI];i <= theMV.argT[ 11; i++) 
theMSP-»MVTLi Je theMV; 


/* Allocate MIVT (Menu Item Values Table*/ 
if (BitTstC&theMF, _MFALOCTB)) 

if C! CtheMSP— МІҮТН- 

(long **)NewHandleCCallocCount* 1)*sizeof Clong)))) 
MSErrExitCprogNum, 23, menuID, 2); 
elsefor Ci=0;i <= allocCount; i++) 
¥((*theMSP->MIVTH)+i J=theMSP->MIVTnul1Val; 
/* MIVT Prep */ 
if (MIVTFct1) 
( {ҺеМ$Р-›ргос10Ї@]=МТҮТЕс{ 1; 
BitSetCtheMSP-»MVT, _MFPRCFLG); 


if CMIVTFct2) 
{ theMSP->procID[1]=MIVTFct2; 
BitSetCtheMSP- MVT, .MFPRCFLG* 12; 


/* Build MIVT (Menu Item Values Table*/ 
if (BitTstC&theMF, _MFBLDTAB)) 
if С! theMSP-—»procIDI21) 
MSErrExitCprogNum, 12, menuID, ð); 
else MSCallProc CtheMSP, menuID, 2,9); 
/* Set Menu and TogFlgs for expanded range */ 
if (BitTstC&theMF, _MFSETXRG)) 
if CIXBitTstC&theMF, _MFEXPRNG))) 
MSErrExit(progNum,06,menuID,0); 
else 
(  defPosstheMV .argT[3); 
if (! defPos) 
( defVal=theMSP->MIVTdef Val; 
defPos-staticCount ; 
if CdefVal) 
for Ci=defPos;i <= dynemCount;i**) 
if (defVal == MSGetMIVTCmenuID, 122 
( defPos=i;break; } 


) 
CheckItemCtheMSP-? MH, defPos, 1); 
MSTogB i t(menuID, def Pos); 


/* Set Menu and TogFlgs to PREVious state */ 
if (BitTstC&theMF, -МҒЗЕТРКЕ2) 
if € ! CtheHdlsGetResourceC MSPRVTYP ,menuID)) ) 
MSErrExitCprogNum, 12, menuID, 0); 
else 
(  HLockCtheHd1); 
MSAdjTog(menulD, *theHd1 , *theHd1*sizeof CToggleF lag); 
HUn lock( theHd1); 


) 
/* Execute PROC2 if attached */ 
MSCallProc CtheMSP,menuID, 0, 1); 
HUnlock( theMSH); 
return (Cint)theMSP->MH); 


MSInsert(menuID, beforeID) 
short menuID, bef oreID; 

( /* Call after MSMake, inserts MST menu in MenuBar*/ 
MSHd1 theMSH; 
MenuHandle theMH; 
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short progNum=04 ; 

HLock(( theMSH=MSGe tMSHCmenuID, progNum))); 

theMH=(* theMSH)-> MH; 

if С! theMH) MSErrExit(progNum, 02 ,menuID, 0); 

if (BitTstCC*theMSH)->MVT, _MFSUBMEN)) 
InsertMenu( theMH, 21); 

else if CbeforeID != 0) InsertMenu(theMH, beforeID); 
else InsertMenuCtheMH, (*theMSH)->beforeID); 


HUnlock(theMSH); 


MSDispatchCmenuID, 


( 


i temNumber ) 

short menuID; 

short itemNumber ; 

/*Call after MenuSelect, dispatches to MSDispatch1, which 


is recursive, and therefore needs а locked MSPtr */ 


MSHd1 theMSH; 
MSPtr theMSP ; 
short progNum-2 ; 
int MIVTFct 1; 


Handle theHandle; 


if C! CtheMSH=(MSHd1 )Ge tResource C. MSMSTTYP , menu ID) return; 
HLockCtheMSH); 

theMSP=*theMSH; 

MSDispatch1(theMSP, menuID, itemNumber); 

MSCallProc (theMSP,menuID, itemNumber, 1); 

HUnlock(theMSH); 


) 
int MSInsMenultem(menuID,menuStr,after,theMV) 


~ 


short nenuID; 

char *nenuStr; 

short af ter; 

MenuVerb *theMV; 

/* Inserts а dynamic, typed item beyond staticCount, if 
enough’ space has been allocated*/ 


short progNum= 12; 

shor t staticCount, dynamicCount,allocCount; 
MSHd1 theMSH; 

MSPtr theMSP ; 


long menL іпеТх(-0х02282000; /* (- pascal string */ 


HLock( ( theMSH=MSGe tMSHCmenuID, progNum 22); 
theMSPz* theMSH; 
MSParseAf ter C theMSP, &ef ter, 
&steticCount , &dynamicCount, &allocCount); 

if CdynamicCount >= el locCount)return (7175; 
if CtheMV-?opCode = = -WTEXTOG 

|| theMV-»opCode == .MVTEXTOG) 

return (-24); /* not implemented */ 

MSShif tCtheMSP, after, 10; 
theMSP-»MVT([after*1] = *theMV; 
if CtheMV-?opCode == _MVMENLIN) 

menuStrsCchar *)(&menLineTxt); 
InsMenuItemCtheMSP-»MH, menuStr, after); 
HUnlockCtheMSH); 
return Caf ter*1); 


) /* Епа of MSDispatch2 

= EM / 

MSDelMenuItem(CmenuID, i temNumber ) 
short menulD; 
short itemNumber ; 

{ /* Deletes dynamic menu item beyond staticCount*/ 
short progNum= 13; 
short staticCount, dynamicCount,allocCount; 
MSHd1 theMSH; 
MSP tr theMSP ; 


HLock(( theMSH=MSGe tMSH(menuID, progNum))); 
theMSP=* theMSH; 
MSParseAf ter CtheMSP , & i temNumber , 
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&staticCount , &dynamicCount, &allocCount?; 
= staticCount) 
= dynamicCount) return (-17); 


if CitemNumber = 
if (staticCount = 
else itemNumber**; 
MSShif tCtheMSP, itemNumber , - 12; 
De 1Menul tem( theMSP-> MH, itemNumber ); 
HUn lock ( theMSH) ; 
return (0); 


) 


MSDisposeCmenuID) 

short nenuID; 

/* Disposes of menu and associated MST structures*/ 
MSHd1 theMSH; 

short progNun=05 ; 


~~ 


theMSH=MSGe tMSHCmenuID, progNum); 

Re leaseResource((*theMSH)-» MH); 

if (BitTstCC*theMSH)->MVT, _MFALOCTB)) 
DisposHandle(C(*theMSH)->MIVTH ); 

Re leaseResource( theMSH); 


) 


MSAdjTog(menuID, theTF , theMSK ) 
short nenuID; 
ToggleFlag *theTF, *theMSK: 
( /* Sets menus to Toggle Flag snapshot, masked*/ 


MSHd1 theMSH; 
MSPtr theMSP ; 

int i; 

short allocCount; 
short progNum-08; 


HLockCCtheMSHzMSGe tMSHCmenuID, progNum))); 
theMSPz* theMSH; 
81] locCount= =(%theMSH)-»allocCount; 
for (1=1; 1 <= allocCount; i++) 
if (BitTstCtheMSK, 122 
if С  BitTstC&CttheMSH)- TF, i) 
IzBitTstCtheTF, i) 2 
( MSD ispatch 1( theMSP, menuID, i); 
MSCallProc (theMSP, menuID, i, D; 


HUnlock(CtheMSH); 
MSAdjPREVCmenuID) 
short nenuID; 
( /* Sets stored MST1 resource to current toggle state*/ 
MSHd1 theMSH; 
Handle — thePREVH; 
Ptr thePREVP : 
short progNum= 10; 
int i; 
short theErr,allocCount; 


theMSH=MSGe tMSHCmenuID, progNum); 
if € ! CthePREVH=GetResource(_MSPRVTYP,menuID)) ) 
MSErrExit(progNum, 12, menuID, Ø); 
allocCountsC*theMSH)-? allocCount; 
HLock( thePREVH); 
thePREVP=* thePREVH; 
for (1=1; i <= allocCount; i++) 
if (BitTstCthePREVP*sizeof (ToggleF lag), i2) 
if С BitTstC&C*theMSH)-> TF, i) 
IsBitTstCthePREVP,i) ) 
if (BitTst(&C*theMSH)-> TF, 1) BitSet( thePREVP, i); 
else BitClrCthePREVP py 
ChangedResDataC thePREVH); 
if CtheErr=ResError()) 
MSErrExitCprogNum, 13, menuID, theErr); 
WriteResourceCthePREVH); 
if CtheErr=ResError()) 
MSErrExitCprogNum, 13, menuID, theErr); 


HUn lock( thePREVH); MSPtr theMSP; 


Re leaseResource( thePREVH); short menuID; 
short itemNumber ; 
( /* core type-dispatching routine - recursive, therefore must 
MSErrExitCprogNum,errNum, menuID, itemNumber) not lock/unlock MST - calls MSDispatch2 for calculating argT 
short progNum,errNum, menuID, itemNumber; default values*/ 
( /* Puts up ап Alert and exits to Finder*/ MenuHandle ^ theMH; 
Str255  txtStr(31]; MenuVerb theMV; 
int i; MVOpCode opCode; 
MVArgT first, last, perent, other; 
sprintf CtxtStr[01, "Ed", ргод№ ит); short progNum=93 ; 
sprintfCtxtStr[1], "$d", errNum); Str255 theSTR; 
sprintf CtxtStr(2], “89* , menuID); int theTVal, flag,i; 
sprintf (txtStr[3], ^$d^, itemNumber ); 
for (1=0;1 < 4; i++) CtoPstr(&txtStr(i12; if CitemNumber > theMSP->allocCount) return; 
ParamText(txtStr [9], txtStr [1], txtStr [2], txtStr(3)); theMH- theMSP-» MH; 
StopAlert(5900,0); theMVs theMSP-»MVT [1 temNumber J; 
ExitToShe11C); opCode=theMV . opCode ; 
) if CopCode <= .MVNORMAL) return; 
if CitemNumber > theMSP-?allocCount) 
int MSTogBit(nenuID, i temNumber ) MSErrExitCprogNum, 17, menuID, i temNumber ); 
short menulD; f irst-theMV .агдТ (8); 
short i temNumber ; laststheMV .argT( 11; 
/* toggles and returns current value %/ parent=theMV .argT [2]; 
( /* Toggles flag апа returns value */ otherstheMV .argT (31; 
MSHd1 theMSH; theTVal-MSTogBi tCmenuID, i temNumber ); 
MSP tr theMSP ; MSDispatch2CtheMSP , menuID, i temNumber , 
short progNum=09 ; 
opCode, &first,&last, &parent, &other ); 
theMSH=MSGe tMSHCmenuID, progNum?; Switch CopCode) 
theMSPz* theMSH; ( 
if CitemNumber > theMSP-^allocCount? сазе _MVCHKTOG : 
MSErrExitCprogNum, 17, menuID, i tenNumber >; CheckItemCtheMH, i temNumber , theTVa12); 
if (BitTstC&theMSP-> TF, itemNumber 2) break; 
( BitClrC&theMSP-» TF, itemNumber2;return(0); ) case _MVTEXTOG : 
else ( BitSet(&theMSP-> TF, itemNumber);return(1); } if (MSGetIndStr(&theSTR,menuID, other+theTVal) < 0) 
) MSErrExitCprogNum, 08, mnenuID, i temNumber ); 
else SetItemCtheMH, i tenNumber , &theS TR); 
MSHdl MSGetMSHCmenuID, progNum) break; 
short nenuID; case C MVENABPR) : 
short progNum; MSTogBitCnenuID, other); 
( /* Gets MST resource handle, on error calls MSErrExit*/ MSEnableCtheMH, i temNumber , theTVa1); 
MSHd1 theMSH; MSEnebleCtheMH, other, ! theTVal); 
if С CtheMSH=CMSHd1 )GetResource(_MSMSTTYP,menuID)) 2 break; 
return CtheMSH 2; cese (_MVNZEXRG) : 
else MSErrExit(CprogNum, 0 1, nenuID, 0); MSClear(CtheMSP, first, last, орСоде); 
) CheckItemCtheMH, i temNumber , 1); 
MSTogBit(menuID, itemNumber ); 
int MSGetTogCmenuID, i temNumber 2 break; 
short nenuID; case C. MVCMRGRS) : 
short itemNumber ; Switch CitemNumber == parent) 
( /* returns current value of togglef lag*/ 
MSHd1 theMSH; сазе(1) : /* Parent */ 
short progNum=06 ; if С! theTVal) 
MSTogB i tCmenuID, i tenNumber 2; 
theMSH=MSGe tMSHCmenuID, ргод№ ит); else 
returnCBitTstC& C* theMSH2-» TF, itemNumber 22; ( MSClearCtheMSP, first, last, opCode); 
) CheckI tem( theMH, i tenNumber , 1); 
if CCitemNumber >= first) 
int MSGetMIVTCmenuID, i temNumber 2 && CitemNumber <= last?) 
short menulD, itemNumber ; MSTogBitCmenulD, i temNumber 2; 
( /* Retrieves the itemnumber entry from MIVTable*/ 
MSHd1 theMSH; break; 
short progNum=07 ; cese (0): /* Member */ 
CheckItemCtheMH, i temNumber , the TVal ); 
theMSH=MSGe tMSHCmenuID , progNum ); if CtheTVal) 
if CitemNumber > (*theMSH)->allocCount) f lag=BitTstC&theMSP-> TF, parent); 
MSErrExitCprogNum, 17, menuID, i tenNumber 2; else 
return (*CC*CEtheMSH)-? MIVTH2* i temNumber 22; flag = ! MSBitOrCtheMSP, first, last, opCode); 
) if (flag) 
(  CheckItenCtheMH,parent,! theTVal); 
MSTogBitCmenulD, parent); 
JE -—— 6-3: c U"SIAHC GONG: ee) 
static MSDispatch1CtheMSP,menuID, itemNumber) break; 
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break; 
cese C MVENBSET) : 
if CitemNumber != parent) 
MSTogBitCmenuID, i tenNumber ); 
else 
( for Ci=first;i <= last; i++) 
if CtheMSP- YWVTLi 1. opCode = = opCode) 
(MSEnab leC theMH, 1, theTVal); MSTogBi tCmenuID, i); } 
if CCitemNumber >= first) && CitemNumber <= lest?) 
MSTogBit(menuID, i tenNumber ); 
else MSEnableCtheMH, i tenNumber , theTVal); 


itemNumber=other ; 
if (MSGetTogCmenuID, itemNumber) == theTVal) 
MSDispatchlCtheMSP ,menuID, i temNumber ) 


break; 
case (_MVTTGSET) : 
if CitemNumber != parent) 
MSTogB i tCmenuID, i temNumber ); 
else 
( for Ci=first;i <= last; i++) 
if CtheMSP—MVTLil.opCode == opCode) 
if (MSGetIndStr(C&theSTR,menuID, 
theMSP-»MVT[il.argTI3]*theTVal) < 0) 
MSErrExi tCprogNum, 28, menuID, i); 
else 
( SetItenCtheMH, 1, &theSTR); 
MSTogBitCmenuID, i); 


if CCitemNumber >= first) && CitemNumber <= last?) 
MSTogB i tCmenuID, i tenNumber ); 
else 
if (MSGetIndStrC&theSTR,menuID, other *theTVal)«0) 
MSErrExit(progNum, 08, тепи1й, 1{епМипбег); 
elseSetItenCtheMH, i temNunber, &theSTR); 


break; 
) 
) 


static MSDispatch2CtheMSP , menuID, i temNumber,, 
opCode, first, last, parent, other) 

MSPtr theMSP ; 

short menuID, i temNumber ; 

MVOpCode opCode; 

MVArgl *first,*last, *parent, *other; 
( /* calculates values for argTs when not specif ied, i.e. 
first&last dd etc.*/ 


int 1,3; 
MenuVerb fakeVerb; 
short dynanCount ; 
Short progNum=11; 


dynamCount=CountMI tems( theMSP-»> MH); 
m CopCode) 


case C MVENABPR) : 
if (*other <= 0) 
*other=itemNumber+(*other?-1: 1); 
break; 
case (_MVNZEXRG) : 
case ( MVCMRGRS) : 
case C MVENBSET) : 
case (_MVTTGSET) : 
if (*first && *last) return; 
else if (*first || *1ast) 
MSErrExitCprogNum, 14, menuID, i tenNumber ); 
for Ci=itemNumber;i > 0;i-) 
if (theMSP- УМҮТЇ11. орСоде == МҮМЕМІ ІМ) break; 
for (jeitemNumber;j <= dynamCount; j++) 
if CtheMSP- MVTE 1. opCode == _MVMENLIN) break; 
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*firstztti; 
*last--j; 
if CopCode == _MVNZEXRG) break; 
if (parent <= Ø) 
*parent=*first; 
else 
( *parentt=*f irst-1; 
if Схрагепі < *first || *parent > *last) 
MSErrExitCprogNum, 16, menuID, i temNumber ); 


) 
if CopCode != _MVENBSET) break; 
if (*other > 0) break; 
i temNumber=(*other )?*f irst-2: 4185442; 
if CitemNumber <= 0 || itemNumber > dynamCount) 
MSErrEx itCprogNum, 15, menuID, i temNumber ); 
for (1=0;1 < _MVARGDIM; IM 
fakeVerb. argl[i]= =theMSP- »MVTCitemNumber 1. argT( i; 
MSDispatch2( theMSP, menuID, i temNumber , MVCMRGRS, 
&fakeVerb. argT[0], &fakeVerb.ergT[1], 
&fakeVerb .argT(21,&fekeVerb .argT(31); 
*otherzf akeVerb .argT(2]; 
break; 


) 


static MSParseAf ter CtheMSP , af ter, 
staticCount, dynamicCount,allocCount) 

MSPtr theMSP; 
short *after,*staticCount, *dynamicCount, *al locCount; 
/*Translates ‘itemNunber defaults for Del/InsMenI tem */ 
*dynam icCount-CountMI tems( theMSP-» MH); 
*staticCountztheMSP-? stat icCount; 
*allocCount=theMSP->al locCount; 
*af ter+=*staticCount; 
if (*efter <= *stat icCount) 

*af ter=*staticCount; 
else if (*after >= *dynamicCount) 

*af ter=*dynamicCount; 


— 


static MSShiftCtheMSP, i tenNumber , direction) 


MSPtr theMSP; 
short i temNumber, direction; 
( /* Del/InsMenItem utility = shifts MVT by +/- 1 */ 
short progNum= 14; 
MenuVerb X *MVTP; 
long *MIVTP; 
ToggleFlag *TFP; 
int i,k, first, last, dynamicCount; 


MVTP=theMSP->MVT; 
TFPz&theMSP-» TF ; 
dynamicCount= CountMI tems( theMSP- -›МН); 
if (BitTstCtheMSP-»MVT, _MFALOCTB)) 
MIVTP=C*theMSP->MIVTH); 
else MIVTP=0; 
ifCdirectiom) (f irst=dynamicCount+ 1; last=i tenNumber * 1; } 
else ( first=itemNumber ; 1ast=dynamicCount; } 
direction*=-1; 
for Ci=first; i-last; it=direction) 
( *(МУТР+1 )-*CHVTP* i *direction); 
k=BitTst(TFP, itdirection); 
if Ck) BitSetCTFP, i); 
else BitCirCTFP, i); 
) if (МІУІР) *CMIVTP*iD-*CMIVTP*i*direction); 
forCi-0;i < _MVARGDIM; i++) *CCchar *)CMVTP*last?*i2-2^WM0' ; 
if (MIVTP) *(MIVTP+1ast)=theMSP-bMIVTnullVal; 
BitCIrCTFP, last); 


) 

static М5Са11Ргос CtheMSP, menuID, i tenNumber , indx) 
MSPtr theMSP ; 
short menuID, itemNumber , indx; 


185 


( /* Gets Handle to and calls MST-»procID[indx] PROC parameter 
using standard interface (menuID,itemNumber, indx) - for 
MSCallProc itself, indx is the procID entry number */ 

int — MIVTFct; 

Handle theHd1; 

int retVal; 

біг255 theStr; 

short ргодМит- 16; 


if С! theMSP-—procID[indx]) return; 
MIVTFct=theMSP-> procID[ indx]); 
if С! BitTstCtheMSP—MVT, _MFPRCFLG+indx)) 

if С! CtheHd]=GetResource(_MSPRCTYP,MIVTFct)) 2 

MSErrExitCprogNum,04,menuID, indx+ 1); 

else (HLock( theHd] );MIVTFct=C int )(*theHd] ); } 

retValsC*CCint. (*)())XMIVTFct))) 
(theMSP ,nenuID, i temNumber , indx); 

if (retVal < 0) 

MSErrExit(progNum,05,menuID, 

(-retVal*256)+indx); 
if C! BitTst(theMSP->MVT, MFPRCFLG+ indx2) 
HUnlock( theHd1); 


static MSEnable( theMH, i temNumber , f lag) 
MenuHandle theMH; 
short itemNumber , f 18g; 
( /* Boolean paremeter added to ToolBox routine*/ 
if (flag) Ena&blelItemCtheMH, i temNumber ); 
else DisebleItemCtheMH, i temNumber 2; 


) 
static MSCleerCtheMSP,f irst, last,opCode) 


MenuStuff *theMSP; 
short first, lest; 
MVOpCode орСоде; 


/* Clears Toggle Flags and unchecks menu items Гог 
MenuVerbs in renge having same opCode */ 


short i, theMark; 
forCisfirst;i <= last; it+) 
if (theMSP->MVTLi].opCode == opCode) 
( BitCIrC&theMSP-> TF, i); 
GetI temMark( theMSP-> МН, i, &theMark); 
if CtheMark != noMark) 
CheckI tem( theMSP->MH, 1,02; 


) 

stetic MSPcat(s1,s2) 

char *s1,*s2; 

(int i; BlockMoveCs2*1,s1**s1*1,*s2); *s1*-*s2;) 


static int MSBitOrCtheMSP,first, last,opCode) 


MSPtr theMSP ; 

short first, last; 

MVOpCode орСоде; 

/* returns (i..j) togbit К — —*/ 
short i; 


for Cisfirst;i <= last; i++) 
if CtheMSP—MVTLil.opCode == орСоде) 
if (BitTstC&theMSP-> TF, 122 
return(1); 
return(0); 


static int MSGetIndStr(theStrP,menuID,strIndx) 
сһаг XtheStrP; 
short menuID, str Indx; 

( /* Like NOT IN ROM GetIndStr, except returns length, 
or -1 if Indx out of bounds */ 


MSHd1 theMSH; 
Handle — theSTRH; 
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int i,mexIndx, len; 
char *s; 
short progNum= 19; 


theMSH=MSGe tMSHCmenuID, progNum?; 

menu ID-C*theMSH2-» t tgStrID; 

ifC !CtheSTRH=GetResource(_MSSTRTYP,menuID))) return (71); 
maxIndxs*CCshort *)(*theSTRH)); 

if C(strIndx > maxIndx) || CstrIndx <= 82) return (-1); 
s=*theSTRH + sizeof (short); 

for (1=1; i < strIndx; i++) st=Cunsigned char )(*s)+1; 


len=Cunsigned char )(*s)+1; 
*theStrP-0; 
BlockMove(s, theStrP, len); 
returnClen); 


) 
Listing: MST.C 


/* MST.C = minimal MenuStuff Test Program*/ 
BOptions +J +K +Z 

8 include “MS.h” 

include *Events.h^ 

include *Window.h^ 

"define .QuitMenNum 2 

define  QuitItemNum 1 

mainC) 


EventRecord  theEvent; 


char C; 

WindowPtr theWindow; 
short windowCode; 
long menuResult; 
int 1,3; 

Handle theHandle; 
Str255 theStr; 
InitMenus(); 

InitCursor(); 


i=CountResources(_MSMSTTYP ); 

for Cj*1;j <= 1;]++) 

{ theHandle=Get IndResource(_MSMSTTYP, j); 
GetResInfoC theHandle, &windowCode, &menuResul { &theStr ); 
MSMakeCwindowCode, 0,0); 
MSInsertCwindowCode, 0); 


DrawMenuBar C ); 
FlushEventsCeveryEvent); 
while C1) 
( if CGetNextEventCeveryEvent, &theEvent)) 
Switch CtheEvent . what) 
( cese (keuDown) : 
c=theEvent.message & 0х000000ҒҒІ; 
if CtheEvent .modif iers & cmdKey) 
if (с == 'q' 
ExitToShel1(); 
break; 
case (mouseDown) : 
windowCode=F indW indowC&theEvent . where, &theWindow); 
if CwindowCode == inMenuBar ) 
(  nmenuResultzMenuSelect(&theEvent . where); 
MSD ispatchCHiWord(menuResul t), 
LoWord(menuResult) ); 
if CHiWord(menuResult) == .QuitMenNum) 
if (LoWord(menuResult) == Quit] temNum) 


ExitToShe11C); 
HiliteMenuC0); 
break; 
))) 
Listing: MST.Link 
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;  MSTst.link 


/Start QuickStart 
/Output MST 

МТ .Ве1 

М5.Ре1 

Standard Library.Rel 
/Include MS.rsrc 
/Include MSTtst1.rsrc 
/Include MSPROC.rsrc 
/End 


Listing: MSProci.C 


/*MSPROC1.c = PROC Resource 1,sets MIVT[i] to fontNum */ 
"Options +J +K +Z 

"include “MS.h” 

MSPROC 1CtheMSP , nenuID, i temNumber , f 1g) 


81 locCount=theMSP-> а] locCount; 


by teOf f Se t=_MSF IXLEN*CallocCount* 1)*sizeof(MenuVerb); 


if С *Cshort *)CCchar. *)theMSP+byteOffSet) < 1) 


return(-3); /* must find font menu ID somewhere! */ 


fontNumz*C*MIVTH* i temNumber ); 


otherMenuID-*(Cshort *)(Cchar *)theMSPtbyteOffSet)+1); 


otherMSH- CMSHdl2GetResourceC  М5М5ТТҮР, otherMenuID); 
if CotherMSH == 0) return (-4); 

if C!CotherMH=(*otherMSH)->MH)) return (-4); 

stat icCount=(*otherMSH)-»staticCount; 
MIVTH2C*otherMSH2-»MIVTH; 
dynamCount=CountMI temsC C*other MSH)-? MH); 


for Ci=staticCount;i <= dynamCount; i++) 
( fontSize=*(*MIVTH+i); 
if (RealFont(fontNum, fontSize)) 
SetItemStyleCotherMH, i, out] ineStyle); 
else 
Seti temStyleCotherMH, 1,0); 


MSPtr theMSP ; 
short menuID, itemNumber , f 1g; return (0); 
short dynamCount, stat icCount, fontNum, i; mainC) 
Str255 fontName; (} 
staticCount=theMSP->staticCount; 
dynamCountzCountMI tems( theMSP-) МН); Listing: MSProc2.Link 
for Ci=staticCount;i <= dynamCount; i++) 
(  GetItemCtheMSP-? MH, i, &fontName); ,MSPROC2.link - link files for other PROCS similar 
GetFNumC&fontName, &fontNum); /Start QuickStart 
*CClong *)C*theMSP->MIVTH)+i 5f ontNum; /Output MSPROC2 
/Strip 
return (0); MSPROC2 .Rel 
Standard Librery.Re] 
nainC) /End 


0 


Listing: MSProc3.C 


Listing: MSProci.Link 


/*MSPROC3.c = 


,MSPROC. link numeric in MIVT */ 
/Output MSPROCI 80ptions +J +K +Z 
MSPROC1.Rel 8include “MS.h” 
/End 
MSPROC3(theMSP,menuID,itemNumber,f1g) 

Listing: MSProc2.C MSPtr theMSP ; 

short nenuID; 
/* MSPROC2.c = PROC Resource 2 : when Font menu selected, short itemNumber , f 1g; 
sets Font Size to outline if size is RealFont*/ 
ROptions +J +K +Z int i,j,k; 


#include “MS.h” 
"include "Font.h^ 
MSPROC2( theMSP , nenuID, i temNumber , f 19) 


MSPtr theMSP ; 

short menuID; 

short TtemNumber , f 1g; 

int 1 

short dynamCount, staticCount, al locCount, 
fontNum, fontSize, byteOf fSet, otherMenulD; 

MSHd1 otherMSH; 

long X*MIVTH; 


MenuHandle otherMH; 
5іг255 fontName; 


if С! BitTstCtheMSP->MVT, _MFPRCPAR)) return(-1); 
if CitemNumber « NULL) 

return(-2); 
dynamCount-CountMI tems theMSP-» MH); 
ifCitemNumber == NULL) /* may be called at set up */ 
( for (1=1;1 <= dynamCount; 1++) 

if (BitTstC&theMSP-» TF, i2) 

break; 
itemNumberzCi > dynamCount)?1:i; 


) 
MIVTH=theMSP->MIVTH; 
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short du⁄unamCount; 
cher  s1[256],s2[256]; 


dynamCount-CountMItems(theMSP-» МН); 


for (1=1;1 <= dynamCount; i++) 
( if CtheMSP—MVTLil.opCode == _MVMENLIN) 
continue; 
GetItemCtheMSP-»MH, i,s1); 
PtoCstr(s1); 
2:0; 
while C! isdigit(*(s1*j)) && j < strlen(s1)) jtt; 
if (j < strlen(s15) 
( к=0; 
while (1$91914(*($1+])) && j < strlen(s1)) 
( *(s2+k)=*(s1+j); 
jtt;ktt; 


¥(s2tk )=’\0'; 

k=atoi(s2); 

*(C*¥theMSP->MIVTH)+i =k; 
else *((*theMSP->MIVTH)+i )=8; 


return (8); 


PROC Resource 3, converts Font size text to 
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main() 


() 
Listing: MSProc3.Link 


;MSPROCS. link 

/Start QuickStart 
/Output MSPROC3 
MSPROC3 . Re] 

Standard Library.Rel 
/End 


Listing: MSPROC.R 


ж MSPROC.R = creates PROC 
Resources 


MSPROC .rsrc 
TYPE PROC 


‚ 1 
MSPROC 1 


,2 
MSPROC2 


,3 
MSPROC3 


Listing: MS.R 


х Alert resources for 
MSErrExit 
x 


MS .rsrc 
Type ALRT 


‚500 
66 68 266 427 
500 
4444 


Type DITL 


,900 
10 
ж 1 
BtnItem Enabled 
161 262 185 328 
Finder 


x 2 

BtnItem Enabled 
159 173 185 244 
Restart 


ж 3 

StatText Enabled 

11 98 28 304 

Menu Stuff Problems !! 


X 4 

StatText Enabled 
54 98 73 342 

^0 


x 5 

StatText Enabled 
131 98 152 333 
^2 
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* 6 

StatText Enabled 
80 98 117 352 

^] 


Listing: MSTtst1.R 


* Sample Test resources 
MSTtst1.rsrc 


TYPE MENU 


‚1 
\14 


‚2 
File 
Quit/Q 


‚3 

Test 

Font/A1B!M 
Size/\1B!\5 
Style/\ 1B! \6 

| \ 12CheckTog 
TextTog 0 
EnabPair 1 
CEnabPair 2 

(- 

Enabled Parent 1 
Enabled Member 1 
(- 

(Enabled Parent 2 
(Enabled Member 2 
(- 

TextTog Master 
TextTog Member 


‚4 
Font 


‚5 
Size 
9 
111212 
18 
20 
24 


,6 

Style 
!\12Р1а1п 
Bold«B 
Itelic«I 
Under ined«U 
Outlined«0 
Shadowed<S 


* File Menu 
TYPE MST = GNRL 
2 
: Menu Handle place holder 


.H 

0000 0000 

* Resource type for AddRes- 
Menu 


.H 

0000 0000 

х MIVT handle place holder 
.H 

0000 0000 

ж procID table 


H 
0000 0000 0000 0000 


XMIVT default and null values H 
H 


| 
0000 0000 0000 0000 


ж static, allocCount, 


beforeID, STR* ID 
‚Н 

0001 0001 0000 0000 
*Toggle Flags 

H 


0000 0000 0000 


* MVT - zeroeth entry 


contains Menu Flag 
‚Н 
0000 0000 0000 


XStaticCount Menu Verbs 


follow : 
.H 
0000 0000 0000 


* Desk Menu 

TYPE MST = GNRL 

‚1 

‚Н 

0000 0000 4452 5652 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 000Ғ 
0002 0000 0000 0000 
0000 8000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
‚Н 

0000 


* Test Menu 3 

TYPE MST = GNRL 

‚З 

‚Н 

0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0010 0010 
0000 0003 GAGO 0000 
0000 0080 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0100 0000 0000 
0200 0000 0000 0300 
0000 0000 0300 0000 
ҒҒ00 8000 0000 0000 
0600 0000 0000 0600 
0000 0000 8000 0000 
0000 0600 0000 ҒҒ00 
0600 0000 FFOO 8000 
0000 0000 0700 0000 
0000 0700 0000 0000 


* Size Menu 


ТУРЕ MST = GNRL 
,5 


0000 0000 0000 0000 
0000 0000 0000 0003 
0000 0000 0000 0000 
FFFF ҒҒҒҒ 0001 0005 
0000 0000 0000 0000 
0000 3000 0000 0000 
0400 0000 0200 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 


Н 
. 
0000 0000 0000 


* Font Menu 

TYPE MST = GNRL 

‚4 

‚Н 

0000 0000 464Ғ 4Е54 
0000 0000 0000 0001 
0000 0002 0000 0000 
ҒЕҒҒ ҒҒҒҒ 0001 0006 
0000 0000 0000 0000 
0000 FD40 0000 0000 
0400 0000 0100 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
‚Н 

0000 0000 

x**** — PROC PARAM 


.H 
0001 0005 


* STYLE Menu 

TYPE MST = GNRL 

, 

‚Н 

0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0006 0006 
0000 0000 4000 0000 
0000 0100 0000 0000 
0500 0000 0000 0500 
0000 0000 0500 0000 
0000 0500 0000 0000 
0500 0000 0000 0500 


.Н 

0000 0000 

ТҮРЕ STR 

* Text Toggled strings 
‚3 (32) 

6 

TextTog 1-0 

TextTog 1 - 1 


TextTog Master - 
TextTog Master - 
TextTog Member - 
TextTog Member - 


—  — Со 
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Programmer s Workshop 


HFS Transfer DA 


Transfer DA 
The Transfer DA is a small desk accessory that adds a 
Transfer menu to any application that supports desk accessories. 


When Apple killed the Minifinder, my work habits were 
shattered. I tried Oasis, a Finder substitute, fora while but I didn’t 
like the way the working directory was changed by launching a 
program; that is, if I launched, say, Macwrite, and opened a file, 
the sfget dialog came up showing the directory that contained 
Macwrite, rather than the one I had been working in. I had to 
navigate through folders to return to my work files. 


Transfer solves that problem. Now, I work on the desktop 
but when I want to switch from one application to another, I use 
Transfer. The working directory is unaffected, and I skip the 
Finder. 


This DA illustrates some interesting programming tech- 
niques: it is a segmented DA; it does an HFS search of an entire 
hard disk; it uses the iaznotify hook; and it creates resources with 
TML Pascal (a subject which came up in the May Mac Tutor 
letters column). 


ИЛ А r 


When the DA is launched for the first time, it starts at the root 
of the disk which contains the System folder, and does an HFS 
catalog of the entire disk. It finds each application on the disk, 
and stores the name and directory id in a special resource FILE 
called "Transfer data", in the System folder. Henceforth, it uses 
this file to build the menu (the HFS catalog takes a little time - 
about 30 seconds on my 20 meg hard disk - so you wouldn't want 
to go through it every time). 


Whenan application is selected from the Transfer menu, the 
applications's name and directory id are copied into the DA's 
global data record, and the address of a special launch routine is 
installed in the “iaznotify” low-memory global. The transfer 
may be immediate or delayed; in the first case, the DA will call 
"ExitToShell"; in the second, it will wait for the application to 
quit normally. 


When the application quits, the Mac will prepare to launch 
the next application (usually the Finder). As one of the last steps 
in this process, it will call "InitApplZone" to initialize the heap. 
This trap will, in turn, call the routine whose address is stored in 
"jaznotfy" - ће DA’s launch routine. This routine simply writes 
the name of the desired application to “curappname” (another 
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low-memory global), and sets the directory to the proper direc- 
tory. The Mac will then go ahead and launch the application. Sort 
of a cowbird launch, you might say! 


A mentati 


This is a small DA, a bit over 6K. so why is it segmented? 
Am I just showing off? 


Before "InitApplIZone" calls the launch procedure, the Mac 
Closes all resource files. That means that if the launch procedure 
is in aresource (e.g., the DRVR resource), it will be left in a free 
block. I don’t feel very secure when executing code in a free 
block! The solution is to detach the resource; the block will 
remain allocated until “InitApplZone” actually cleans up ће 
heap - which happens after it calls the launch routine. 


But if the launch routine is part of the DRVR resource, this 
means detaching the DRVR. If we do that, we’ll never know 
about menu selections, since the desk Manager needs a DRVR 
resource to pass DA events to. So the launch routine has to be in 
a separate segment. 


The launch routine is in a PACK resource. The DRVR’s 
“open” routine loads and locks the PACK, and records its 
address. When it wants to call a routine from the PACK, it puts 
a routine selector into register DO and jumps to the PACK. Atthe 
top of the PACK is a jump table that branches to the routine 
corresponding to the selector. 


There are other ways to segment a DA; this is just the way 
I did this one. 


| ith T 


Since it came up in the May letters column, let me say a few 
words on this topic. It's really simple, once you know the 
(undocumented) trick. It's all in the link control file. 


For example, here is a link control file to create an LDEF: 


!fastlist 

/codetype LDEF 1001 *Fast List' 32 
list 

pas$library 

macintfglue 

/end 
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The first line is the linker's start point - the name of the 

main routine. The second line defines the resource type. This 
will be an LDEF, resource id 1001, named “Fast List”, purgeable. 
The next three lines are the object files to link, in the order you 
want them to be linked. And the final line means just whatit says. 


The code itself should be compiled as a unit, and most 
resource types will require that the main routine appear at the 
very top of the resource. 


The two resources in this program are linked a bit differ- 
ently, the DRVR resource because the resource definition re- 
quires a DA header at the top, and the PACK resource because I 
want a jump table at the top. The fact that I left out the first line 
and got away with it suggests that it may not be necessary. 


ing th 


Ihave tested this DA with every application on my hard disk 
(at the time I wrote it). A number of applications require the 
delayed transfer; for example, any program that uses scratch 
files. I found only one that would not work at all. Can you guess? 
That’s right - Microsoft Word. 


Transfer vs, Multifinder 


I leave as an exercise for the reader the problem of making 
thisDA work with the Multifinder. А more fruitful project might 
be converting the DA to an FKEY. 


E229222922222222292222 22922 ЖЖ ЖЖ 2322222 22 4 


tupes.asm 


(c) 1987, 1988 Attic Software 


9 
; 
М 
; 
; 
д 
; 
4 record formats for Transfer 

ккк кик ЕЕЕ 
ы рр ы р OI ыы 


; _ жгесога 
DEODPOOOREEDOOEEREEREEEEEEEXCEOCEEXEEERERXE 


WRthemenu equ 0; MenuHandle 
WRresfactor equ 4; integer 
WRsysdir equ 6; long 
WRpackaddr equ 10; Ptr 
WRleunchpath equ 14; long 
WRiaunchaddr equ 18; long 
WRiazaddr equ 22; long 
WRtheevent еди 26 

; EventRecord 
WR thename equ 42; Str255 


WRtheblock equ 298; hfs block 


ЖЛЕ КЕЛЕЛЕК КЕКЕК 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖКХ 
types.pas 
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(c) 1987, 1988 Attic Software 

Pascal declarations for Transfer 
ЖЖЖЖЖЖЖЖЖХАЖАЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 
unit types; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 
interface 

(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖКХ ) 


uses macintf, hfs; 


(ЖЖЖЖЖЖЖЖАХЖЖЖЖЖХЖЖЖХЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У) 


{уре 
logical - boolean; 
long =  longint; 
shortpointer = “integer; 
longpointer = “long; 


( ЖЖЖЖАЖЖЖЖЖЖХЖЖЖХЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖХЖ 


Progrem constants consist of (1) DA message types (most of 
which are not used in Transfer); (2) low-memory globals; and 
(3) resource ids. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 


const 
accEvent = 64; 
&ccRun - 65; 
accCursor = 66; 
accMenu = 67; 
accUndo = 68; 
accCut = 78; 
accCopy = Tl 
accPaste = 12; 
accC lear = 73; 
goodbyek iss = -] 
curappname = $910; 
erik =  $4552494B; 
f indername = $20; 
ieznotify = $33¢; 
Sysmap = $58; 
menunum = 1001: 
eboutitem = 1; 
builditem - 2; 
finderitem = 4; 
errordialog = 100 1; 
aboutdialog = 1002; 
builddialog = 1003; 
delaydialog = 1004; 
packnum = 1001; 
stringnum = 1001; 
datastart = 1000; 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖЖХ 


А "deskrecord^ is simply ап application’s name and directory. 
We need to know both of these to transfer to that application. 
Ап "таггау” is an array of deskrecords, along with the array’s 
size. 


Finally, а “wrecord” is the DA’s global data. The last three 
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fields C(*theEvent^, “thename” and the varient parameter block) 
аге just scratch areas, used by various routines as local 


variables. 


Putting them here keeps them off the stack. 


ЖЖАЖЖЖЖАЖЖАЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


type 


deskrecord 
dirid 
name 
end; 
deskpointer 
deskhandle 


marray 
count 
data 


end; 
arraypointer 
arrayhandle 


wrecord 
theMenu 
integer; 
packaddr 
launchpath 
long; 
iazaddr 
theEvent 
thename 


wpointer 


= record 
long; 
Str255; 


^deskrecord; 
^deskpointer; 


record 
integer; 
аггау 
(0.. 10001 of deskhandle; 


“marray; 
^arraypointer; 


packed record 
MenuHandle; 
sysdir 
|: Ptr; 
long; 


resfactor 
long; 


leunchaddr 


long; 
EventRecord; 
: Str255; case integer of 
Cinfoblock 
CInfoPBRec); 
2 ; (hblock 
HParamBlockRec); 
3: (wdblock 
WDPBRec); 
end; 
= ^wrecord; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ ) 


implementation 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 


end. 


Cooooocooooooororoorooroeorooororooerooeoorooooeee ) 


4 
2 
2 
2 
2 
2 
4 
д 
7 


КЖКНИН, 
‚ drvrhead.asm 
; (с) 1987, 1988 Attic Software 


; header for DRVR segment of 
; Transfer. 


‚ ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


7 


; ЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ kkk 


2 


includes 


j ЖЖЖЖЖЖЕЖ ЖЖ ЖЕ ЖЖ ЖЖ ЖЕ ЖЖ ЖЖ ХХХ ХХХ 


include sysequ.d 


include types.asm 


; XOOOCOODCODOODOCOOODOODOOCOODCRIOOOOIOODIOOOROEE K 


; imported routines 


; ЖЖЖЖЖЖЖЖЕЖ ЖЕ ЖЖ ЖЖ ЖЖ ХХХ ХХХ ХХХ ХХ 


xref 


open 
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xref ctl 


j RERERAERERER ЖЕ EKER ERE ХХХ ХХ ХХХ ХХХ ХХ 


; exported routines 
} ЖЖЖЖЖЖЖ ЖЖ ЖЕ ЖЖ ЖЖ ЖЖ ЖЖ ARES 


хде! 
xdef 


initglobals 
setdir 


: ЖЖЖЖЖЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖ 


; modified version of the DA header 


М 
P 
; Тһе canonical DA header. This is а 
; supplied with TML Pascal. 

; 


j ЖЖ ЖЖЖЖЖУЖ ЖЖ ЖЖ ЖЖ REA AE EEE RES 


dc.w $0400 ; flags 

dc.w $0000 ; Service dc.w 
; mask 

dc.w $0000 ; nenuID dc.w огпореп 
dc.w orndone ; prime 

dc.w ornct] ; Control 

dc.w orndone ; Status 

dc.w ornclose ; close 
СКК 

dc.w '(c) 1987, 1988 ' 

dc.w ‘Attic Software’ 

dc.w ‘All rights reserved’ 
; ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ AA ХХХ ХХХ 
огпореп 

тоует.1 A9/A1,-CSP) 

моуе.1  A1,-CSP) ; device 

move.] Ай,-(5Р) ; param jsr open 

моует.1 CSP2*,A0/A1 

move.1 jiodone,-CSP) 

rts 
ornct] 

movem.] AØ/A1,-(SP) 

move.]  A1,-CSP) ; device 

move.1  A0,-CSP) ; param jsr ctl 

movem.1 (SP)+,AQ/A1 

move.] jiodone,-CSP) 

rts 
ornclose 
orndone 

move.]  jiodone,-CSP) 

rts 


‚ ЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


; The routine loader moves a selector 
; into 00, and the address of the 

; PACK segment into AØ. It then 

; jumps to the pack (the pack begins 
; with а jump table). 


) 
7 
7 
4 
7 
7 


jp ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 


initglobals 
move.w  "0,D0 
bra.w loader 
setdir 
move.w — 84,D0 
bra.w loader 
loader 


$ffff 


; Open 


191 


моуеа.1 4(5Р),А0 ; globals 
тоуеа.1 WRpackeddr(CA2), Ad 
jmp (A0) 


QERXESEESESEESEESEEEXEXEEEEEEEXTEEESESEEEK 


(ЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 


drvr .раз 


(с) 1987, 1988 Attic Software 

Pascal routines for DRVR segment of Transfer 
Yoxcooxootoeoooeeoooroopooreoopeopeecoeoeoobeeexx ) 
unit drvr; 
(ЖЖЖЖЖЖЖЖЖЖЖХЖЖЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 
interface 
(ЖЖЖЖЖЖЖЖАЖЖЖЖЖХЖЖЖЖЖЖЖАЖЖАЖЖАЖЖАЖЖЖЖЖАЖЖЖЖХЖ) 
uses macintf, hfs, types; 
(ЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ') 
implementation 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖ ) 


procedure initglobals 

(globals : wpointer); external; 
function setdir 

(dirid : long; 

globals : wpointer) : OSErr; external; 


Cxooeoooocroooooroooroorooeooreoreorooorooooeoeeex 


drawscreen 


This routine draws the “About” message in its rectangle. 


XXXXXXXXXXXXXXFXXXXXXXXXXXXXXXXXXXKXXXXKX) 


procedure drawscreen( 
theWindow : WindowPtr; 
theitem : integer); 


var 
theType integer; 
theHandle : Handle; 
thebox : Rect; 


begin 
SetPortCtheWindow); 


GetFNum( ‘monaco’, theType); 
Tex tFont( theType); 
TextSize(9); 


GetDItemCtheWindow, theitem, theType, 
theHandle, thebox); 


theHandle := GetResource( ‘INFO’, 
GetWRef ConCtheWindow2); 

HLockCtheHandle); 

TextBoxCtheHandle^, GetHandleSize(theHandle), 
thebox, 0); 


192 


HUnlockCtheHandle); 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


transalert 


I want 811 the alerts to identify their source, so I made 
them dialogs, in titled windows, and wrote this routine to 
imitate “Alert”. 


This is not the best мау to do it; for one thing, a titled 
window should be dragable. Modal dialogs, therefore, should 
not have titles. I should have simply added a distinctive 
icon to the item lists. 


Since this is the first use of the "resfactor^ field of the 
global record, it’s as good а place as any to explain it. 
This ОА is given а formal resource id of 16, and all its owned 
resources are numbered accordingly. Тһе Font/DA Mover will 
change all these numbers when it installs the DA. “resfac- 
tor”, which is computed in the “open? routine, below, is the 
correction factor that converts the hard-coded resource ids to 
the actual ids in use. 


Note that "resfactor^ doesn't convert the formal ids; it 
actually converts the constants defined іп the “tupes.pas” 
unit, which are nice positive numbers, equal to the resource 
ids plus 16872. 


There's а little bit of code to install the previous 
procedure if this is the “About” dialog. 


ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ У 
procedure transalert 


(dialognum : integer; 
globals : wpointer); 


var 
savedport : GrafPtr; 
theDialog DialogPtr; 
therecord DialogRecord; 
theType integer; 
theHandle : Handle; 
thebox : Rect; 
choice integer; 

begin 


with globals^ do begin 
GetPor tCsavedpor t); 


theDialog := GetNewDialog(dialognum 
+ resfactor, @therecord, 
pointer(- 122; 

SetPortCtheDialog?); 


if dialognum - aboutdialog then 
begin 
GetDItemCtheDialog, 2, theType, 
theHandle, thebox); 
SetDItemCtheDialog, 2, theType, 
HandleC@drawscreen), thebox); 
SetWRefConCtheDialog, dialognum 
+ resfactor); 
end; 


InitCursor; 
ShowWindow( theDialog); 
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repeat 
ModalDialog(nil, choice); 
until choice = ok; 


CloseDialog( theDialog); 
setPort(savedpor t); 


end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


errordisplay 


This routine displays error messages. The texts of the 


messages are in a string list. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


procedure errordisplay 
Cappnum, sysnum, resnum : long; 
globals : wpointer); 


var 
stringl 
string3 
string4 


Str255; 
Str255; 
Str255; 


begin 
InitCursor; 
with globals^ do begin 


GetIndString(stringl, resfactor 
+ stringnum, resnum); 
if stringi = '^ then 
String] := ‘An error has occurred! ’; 


NumToStringCappnum, string3); 

NumToString(sysnum, string4); 

PeremText(stringl, “°”, 
string3, string4); 


SysBeep( 18); 
transalertCerrordialog, globals); 


end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


getapps 


Here it is - the only recursive routine I have ever been 
forced to use! (Recursion is overrated; it is, in my opinion, 
better to avoid recursion, if you can do it in a natural 
fashion. Loops are easier to read, and generally more 
efficient.) 


This routine is passed a directory id, the count of objects 
(files and folders) in that directory, and the volume refer- 
ence number. It indexes through the directory with "PBGet- 
CatInfo”. 


If the object is another directory, it calls itself with 
that directory’s id and count. 


If the object is а file, and if the file is ап application, 
it records its name and the directory id in the application 
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array. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


procedure getapps 


(thedir : long; thecount : integer; 
thevol : integer; 
theHandle : arrayhandle; 
globals : wpointer); 
label 
100; 
var 
index — integer; 
апеггог integer; 
theDialog DialogPtr; 
jndex integer; 
thelength integer; 
thedesk deskhandle; 
begin 


with globals^ do begin 


for index := 1 to thecount do 


with infoblock do begin 
thename := ''; 


ioCompletion := nil; 


ioNamePtr := @thename; 
ioVRefNum := thevol; 
ioFDirIndex := index; 
ioDrDirID := thedir; 


апеггог:= PBGetCatInfoC@infoblock, 
false); 
if anerror € noErr then begin 
errordisplay(101, апеггог, 
2, globals); 
goto 100; 
end; 


if BitAndCioFlAttrib, $10) = $10 then 
getappsCioDrDirID, ioDrNmF1s, 
thevol, theHandle, globals) 
else if ioFlFndrInfo.fdType 
- 'APPL^ then begin 


jndex := theHandle^^.count* 1; 
theHandle^^.count := jndex; 


SetHandleSize 


CHandle( theHandle), 
5 * (jndex + 1)); 


HLockCHandle(CtheHandle)2); 


with theHandle^^ do 
while CIUCompStr ingCthename, 
data[jndex - 11^^.name) < 0) 
and ()пдех › 1) do begin 


dataljndex]:= data[jndex - 11; 
jndex := jndex - 1; 


end; 


thelength:= 10 + length(thename); 
thelength:= 2 * Cthelength div 2); 
theHandle^^.data[jndex] 
‚= deskhandle 
(NewHandleCthelength22; 
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with theHandle^^.data[jndex]1^^ 
do begin 

dirid := thedir; 
name :- thename; 

end; 

HUnlockCHandleCtheHandle)); 

end; 
109: end; 
end; 


end; 


(ЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 


walktree 


This routine catalogs all the applications on a given disk. 

It first puts up а dialog, telling the user what's going on. 

It next calls "PBGetCatInfo^ for the root directory (91гес- 
tory id = 2), to get the number of objects in the root. Then 
it calls “getapps” to walk the HFS tree recursively. 

The collected data is written to the current resource file 
(“Transfer Data’, in the System folder), and the dialog is 
dismissed. 


ЖЖЖЖЖАЖЖАЖАЖАЖЖЖЖЖАЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖАЖЖЖЖАЖЖЖЖЖЖХ)) 


procedure walktree 


(thevol : integer; 
theHandle : arraghandle; 
globals : wpointer); 

var 
savedport GrafPtr; 
theDialog DialogPtr; 
therecord DialogRecord; 
index integer; 
апеггог integer; 

begin 


with globals^ do begin 
GetPort(sevedport); 


theDialog := GetNewDialog(resfactor 
+ builddialog, @therecord, 
pointer(-1)); 

SetPort( theDialog); 

ShowWindow( theDialog); 

DrawDialog( theDialog); 


with infoblock do begin 
ioCompletion := nil; 


ioNamePtr := nil; 
ioVRefNum := thevol; 
ioFDirIndex := 0; 
ioDrDirID :- 2; 

end; 

enerror := PBGetCatInfoC@infoblock, 
false); 


if enerror «€ noErr then 
errordisplay( 102, anerror, 
2, globals) 
else 
getapps 
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(2, infoblock.ioDrNmF is, 
thevol, theHandle, globals); 
end; 


HLock(Hand/e( theHand1le )); 
with theHandle** do 
for index := 1 to count do begin 


AddResource 
(HandleCdatalindex]), ’.Тгп’, 
datastart + index, 
datalindex]** .name); 


SetHandleSize 
CHandleCdatalindex]), 4); 


end; 
HUnlock(Handle(theHandle)); 


CloseDialog(theDialog); 
SetPort(savedport); 


end; 


(ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ КК 


buildmenu 


This routine assembles the necessary data, and builds the 
Trensfer menu. 


It finds the volume reference number of the disk with the 
System folder, sets the directory to the System folder, and 
opens or creates the “Transfer Data” file in that directory. 


If this file lacks а header resource (whether because it was 
just created, or because it has been corrupted), then it must 
be rebuilt, with “walktree’. 


Then the menu is built. The menu resource is loaded, and 
the fourth item set to the name of the current Finder. The 
remainder of the menu is copied from the resource file. 


oXooooooeooroeooeeoooooooooocpeooopboopeoeeemkx У 


procedure buildmenu(globals : wpointer); 
label 
100; 
уаг 
thepointer shortpointer; 
thevolume integer; 
theres integer; 
theHandle arrayhandle; 
index integer; 
jndex integer; 
thedesk Handle; 
theID integer; 
theType ResType; 
anerror integer ; 
begin 


with globals^ do begin 


thepointer :- shortpointer(sysmap); 
anerror := GetVRefNum 
Cthepointer^, thevolume); 
if anerror € noErr then begin 
errordisplay( 103, anerror, 
3, globals); 
goto 100: 
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end; а 


enerror := setdir(sysdir, globals); This routine is more ог less straight out of Tech Note 77, 
if апеггог О noErr then begin pages 3 and 4. It returns а working directory reference 
errordisplayCi04, anerror, number for the System folder, suitable for use in file system 
3, globals); calls. 
goto 100; 
end; Step one is to find the volume reference number of the 
volume that holds the System folder. “sysmap” is the file 
thename := ‘Transfer Data’; reference number of the System file Can open file), so 
theres := OpenResFileCthename); А *GetVRefNum^ will find the volume refence number of the System 


if ResError = fnfErr then begin 


file and, of course, the System folder. 
CreateResF i leCthename?; 


theres := OpenResFileCthename); Step two is to get the directory id, with а call to 
end; *PBHGetVInfo^. The directory id is returned in the 
if ResError € noErr then begin *ioVFndrInfo[ 1]^ field of the HParamBlockRec. 
errordisplay( 105, ResError, 
3, globals); Finally, *PBOpenWD^ will return the System folder’s working 
goto 100: directory reference number, which can be used as а volume 
end; reference number in file system calls. 
theHandle ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 
:= arrayhandle 
(Get IResourceC* . Trn^, function systemvol 
datastart)); (globals : wpointer) : integer; 
if theHendle = nil then begin 
theHandle :- arrayhandle var 
(NewHand1/e(6)); thepointer ‚ . Shortpointer; 
theHandle^^.count := 0; thevolume integer; 
theHandle** .data[@] anerror integer; 
:= deskhandleC(NewHandle( 162); 
AddResource(Handle(theHandle?, begin 
‘.Тгп’, datastart, °’); 
walktreeCthevolume, with globals^ do begin 
theHandle, globals); 
SetHandleSize thepointer := shortpointer(sysmap); 
CHandle(€theHandle), 2); anerror := GetVRefNumCthepointer^, 
end; thevolume); 
theMenu := GetMenuCresf actor with hblock do begin 
+ menunum); ioNamePtr := nil; 
BlockMove(Ptr(f indername), ioVRefNum := thevolume; 
Ptr(@thename), 16); ioVolIndex := 0; 
SetItemCtheMenu, 4, thename); end; 
enerror :- PBHGetVInfoC@hb lock, 
jndex := 1; false); 
for index := 1 to theHandle^^.count 
do begin with wdblock do begin 
thedesk := GetlResource(’. Irn’, ioWDDir ID 
datastart + index); : = Wblock. ioVFndrInfol 11; 
if thedesk © nil then begin ioNemePtr := nil; 
AppendMenuCtheMenu, “.Тгп”); ioVRefNum := thevolume; 
GetResInfoCthedesk, theID, ioWDProcID := erik; 
theType, thename); end; 
SetItemCtheMenu, jndex + 4, enerror :- PBOpenWDC@wdblock, 
thename ); false); 


jndex := jndex + 1; 


end; systemvol := wdblock. ioVRefNum; 
end; 
end; 
InsertMenuCtheMenu, 02; 
DrawMenuBar ; end; 
CloseResF i leCtheres?; (YXXXXXXXXXXXXXXXXXXXXXXX1XXXXXXXXXXXXX3 
100: rebuildmenu 
end; 
If the “Rebuild menu” item is chosen from the menu, ог an 
end; application is chosen which can^t be found, Transfer will 
rebuild the menu from scratch. It does this by deleting the 
(ЖЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖКХ “Transfer Data” file, and calling *buildmenu". 
systemvol EXXKXKKKKAAKAAAAAKAKAAEKAAKAKAAAKAKAA KKK У 
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procedure rebuildmenu 
(globals : wpointer); 


var 
anerror integer; 
begin 
with globals^ do begin 


DeleteMenu(resfactor + menunum); 
Re leaseResource(Handle( theMenu)); 
anerror := FSDelete 
(“Transfer Data’, 
systemvol(globals)); 
buildmenu(globals); 


end; 
end; 


(ХХХХАХА ХХ ХА ХХХ ЖЖ ЖЖ ЖЖ ХХ ХХХ 


dof inder 


If the “Finder? item is chosen from the menu, then no 
transfer is desired, so restore the “iaznotify” hook to the 
value it held when Transfer was launched. (This isn’t quite 
right, since something besides Transfer may have changed it 
since then. but I don't see any way to correct for that...) 


If the option key is down, do nothing else. 


Otherwise, do 
an immediate transfer by calling “ExitToShel1’. 


XXXXXXXXXXXXX1XKXXXXXXXKXKXKXXXXXXXXXXKEXXK) 


procedure dofinder(globals : wpointer); 
var 

thepointer longpointer; 
begin 


with globals^ do begin 


thepointer 

‚= longpointer(iaznotifu); 
thepointer^ := iazeddr; 
if GetNextEventCO, theEvent) then 


if BitAndCtheEvent .modif iers, 
optionKey) = Ø then 
ExitToShe11; 
end; 


end; 


(ЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 


clickmenu 


The first few menu choices аге handled by routines above. 

If ап application is chosen, we need to get (1) the 
application” name, and (2) its directory. Тһе name is easy; 
it^s on the menu. To get the directory, we have to go back to 
the “Transfer Data”? file. 


Once we have the application’s directory, the next thing to 
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do is to make sure it’s there. Transferring to а non-existent 
application will cause a system bomb. 


If everything is ok, then if the option key is down, prepare 
to do a delayed transfer; otherwise, do an immediate transfer 
by calling “ExitToShel1’. 


ЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ) 


procedure clickmenu 


Citemchoice : integer; 
globals : wpointer); 
label 
100: 
уаг 
theres integer; 
thedesk deskhandle; 
the info FInfo; 
thepointer longpointer; 
anerror integer; 
begin 
with globals^ do begin 
case itemchoice of 
eboutitem 
transalertCaboutdialog, 
globals); 
builditem i 
rebuildmenu(globals); 
f inderitem : 
dof inder(globals); 
otherwise 


thepointer := longpointer 
(iaznotifu); 
thepointer^ := launchaddr; 


anerror :- setdir(sysdir, 
globals); 
if anerror «€ noErr then begin 
errordisplay( 196, anerror, 
3, globals); 
goto 100; 
end; 


theres := OpenResFile 
(‘Transfer Data’); 
if ResError © noErr then begin 
rebuildmenu(Cglobals); 
goto 100; 
end; 


GetItemCtheMenu, 

itemchoice, thename); 
thedesk :- deskhandle 

(Get INamedResource(’.Trn’, 

thename )); 
DetachResourceCHandle(thedesk)); 
CloseResF ileCtheres); 


if thedesk = nil then begin 
rebuildmenuCglobals); 
goto 100; 

end; 


anerror := setdir 
(thedesk^^.dirid, globals); 
if anerror © noErr then begin 
rebuildmenu(globals?; 
goto 100; 
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епа; 


enerror :- GetFInfoCthename, 
0, theinfo); 
if enerror © noErr then begin 
rebuildmenu(globals); 
goto 100: 
end; 


leunchpath := thedesk**.dirid; 
if GetNextEvent(@, theEvent) then 


if BitAndCtheEvent modifiers, 
OptionKey) = Ø then 
ExitToShe11 
else begin 
ParamText(thename, 


7” f Cay. 


trensalert(delaydialog, 
globals); 
end; 
end; 
100:  HiliteMenuC0); 
end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


ореп 


This із the canonical DA open routine. If the DA has 
already been opened, device.dCtlMenu will be nonzero; do 


nothing. Otherwise, Allocate the globals, and fill in а few 
fields. Of particular interest is the calculation of "resfac- 


tor” by the magic formula $BFEØ - 32 * dCtlRefNum - 1000. 


This, assuming I have given the DA the formal resource id of 
16, allows be to refer to owned resources by ids from 1000 to 


1031, adding resfactor to convert to the actual values. 


Next, load and detach the PACK segment. Апа lock it; it’s 


created locked but why take chances? 


Finally, call *initglobals^ to fill in the rest of the 
fields, and “buildmenu” to set up the menu. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ +) 


procedure ореп(уаг device : DCtlEntry; 
var block : ParamBlockRec); 

var 
globals wpointer; 
packhandle Handle; 

begin 


if device.dCtlMenu = 0 then begin 


globals :- wpointer 
(NewPtr(sizeofCwrecord))); 
if globals © nil then 
with globals^ do begin 


with device do begin 
resfactor :- $ВЕЕЙ 
- 32 * dCtlRefNum - 1000; 
dCtlMenu := resfactor 
* menunum; 
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dctlwindow := nil; 
dCtlStorage 
:* HandleCglobals); 
end; 


packhandle :- GetResource 

C'PACK^, resfactor + packnum); 
De tachResource(packhandle); 
HLockCpackhandle?); 
packaddr :- packhandle^; 


initglobalsCglobals); 
buildmenu(Cglobals); 


end; 
end; 
end; 
( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


ct] 


The canonical Control routine. The only events we're 
interested in are menu clicks; if we get one, call "click- 
menu”. 


ЖЖЖЖЖАЖЖЖЖЖЖАХЖЖЖЖЖЖЖЖАЖЖЖЖЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


procedure ctl(var device : DCtlEntry; 
var block : ParamBlockRec); 
var 
globals wpointer; 
begin 


if Cdevice.dCtiMenu € 0) 
and (block.csCode = accMenu) 
then begin 
globals := wpointer 
(device.dCtiStorage); 
clickmenu 
(block.csPeram[1], globals); 
end; 


end; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
епа. 


(ЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖАЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


/codetype DRVR 16 ‘Transfer HD’ 16 
drvrhead 

drvr 

pas$library 

macintfglue 

/end 


` ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


packhead.asm 


(c) 1987, 1988 Attic Software 


header and assembly routines for 
PACK segment of Transfer. 


"- e We `. We We We We ` 
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; 
ыыы 


а еы ын 


; exported routines 
; OOOODDODCEXSERDDEREEX DENEN EE SER SEE EE X 


xdef setglobal 
xdef getglobal 
xdef runiaz 


‚ ХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХ ХХХ ХХ ХХХ 


7 

д 

; The jump table begins with a jump 

3 into the body of the table, indexed 
; by 00 (the routine selector). Then 
| it branches to the appropriate 

: routine. 

7 


LDEODOUEEESEEEESEEESEXSESEESETERSEESESSSN 


xref | initglobals 
xref | setdir 


jmp  2(РС,0б.м) 
bre.w initglobals 
bra.w setdir 


“ХХХХХХХХХХХХХХХХХХХХХХАХХХХХХХХХХ ХХХ Ж 


The global access routines provide 
а way to зауе the address of the 
global record, which would 
otherwise be lost. This is done by 
writing the address into а four- 
byte constant in the PACK segment. 


7 

ГА 

7 

7 

д 

7 

; Note: writing to code segments is 
I frowned upon in some circles. This 
) objection has a legitimate basis: 
j self-modifying code is а horror. 

р It таке$ debugging difficult, and 
р maintenance impossible. (5 points: 
) where in “Inside Мас” are uou 

: instructed to write self-modifying 
; code?) In this instance, I an not 
; modifuing code; I am modifuing 

) data, and there's nothing wrong 

; with that. 

2 

7 

д 

7 


procedure setglobal(value : long); 
function getglobal : long; 


J ЖЖЖЖЖ ЖЕ ЖКХ ХЕХЕ ХЕХЕ ХЕХЕ ХЕ ХЕХ ХЕХ 


module ‘access’ 


setglobal 
movea. | (SP )+, Ad 
lea — dummy, A1 
move.1 (5Р)%, (А1) 


jmp (АЙ) 
getglobal 
movea. | CSP )+, Ай 
моуе.1 dummy, CSP) 
jmp (A0) 


dummy 
dc.»  'xxxx' 


QGODEXEEXEEXXEEEERXEEXECEODOOORDECEOORXOUEX SEXO 


procedure runiazCiazaddr : long) 
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; The runiaz routine zeros the 

; *iaznotify^ hook, and calls the 
| routine that preceded Transfer’s 
5 routine, if any. 


PEERAA AAAA OKEE 


module ‘runiaz’ 


гип1а2 
с1г.1 $336 
тоуеа.1 4(SP),A0 
поуе.1 (SP)+, (ӨР) 


спра.1 80 А0 
beq.w 10001 
поуе.1 AQ,-CSP) 


(0001 
rts 


‚*ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖ 


(ЖЖЖЖЖЖХЖЖЖЖЖХЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖ 


pack .pas 


(с) 1987, 1988 Attic Software 


Pascal routines for PACK segment of Transfer 


ЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ ) 


unit pack; 
(ЖЖЖЖЖХЖЖЖХЖХЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


interface 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 


uses macintf, hfs, types; 


(ЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ) 


implementation 
(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ Х У 


procedure setglobal 

(value : long); external; 
function getglobal : long; external; 
procedure runiaz 

Сізгәдіг : long); external; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
systemdir 

This routine is more or less straight out of Tech Note 67. 
It returns a directory id for the System folder, suitable for 
use in “SetVol’ calls. 

Step one is to find the volume reference number of the 
volume that holds the System folder. “sysmap” is the file 
reference number of the System file Can open file), so 
*GetVRefNum^ will find the volume refence number of the System 
file and, of course, the System folder. (The Tech Note skips 
this step; it searches the boot drive for a System folder, and 
may not find one.) 

Step two is to get the directory id, with a call to 
*PBHGetVInfo^. The directory id is returned in the 
*ioVFndrInfo[ 11^ field of the HParamBlockRec. 

ЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ KKK +) 


function systemdir 
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(globals : wpointer) : long; 


var 
thepointer shortpointer; 
thevolume integer; 
enerror integer; 
begin 


with globals^ do begin 
thepointer :- shortpointer(Csysmap); 
anerror :- GetVRefNumCthepointer^, 


thevolume ); 
with hblock do begin 
ioNamePtr := nil; 


ioVRefNum := thevolume; 
ioVolIndex := 0; 


end; 
anerror :- PBHGetVInfoC@hblock, 
false); 
systemdir := hblock.ioVFndrInfo[ 11; 
end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
setdir 


This is just a shell around "PBHSetVol". 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 


function setdir 

(dirid : long; 

globals : wpointer) : OSErr; 
begin 

with globals^ do begin 


with wdblock do begin 
ioCompletion := nil; 


ioNamePtr := nil; 

ioVRefNum := 0; 

ioWDDirID := dirid; 
end; 


setdir :- PBHSetVol(@wdblock, 
false); 


end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
postlaunch 


This is the routine that performs the actual launch. It 
is called by "InitApplZone^ throught the "iaznotify^ hook. 

First, recover the global record with a call to “getglo- 
bal”. This routine is called after all the resources have 
been released; the DRVR segment is no longer around, and even 
if it was, "postleunch^ isn’t called by it, so we can’t find 
the globals in the usual way. “getglobal” will return a long 
word stored right in the PACK segment, which has been previ- 
ously set to a pointer to the globals. 

Next, *"postlaunch^ will call any routines that were 
already installed in “iaznotify” when "postlaunch^ was 
installed there, via the “runiaz” routine. 

Then it calls “setdir” to set the volume to the folder 
containing the chosen application, and copies the 
applications’s name to "curappname^. Тһе system will now be 
fooled into launching that application instead of the Finder. 
ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖХ ) 


procedure postlaunch; 


var 
globals wpointer; 
anerror integer; 
begin 
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globals :- wpointer(getglobal); 
with globals^ do begin 
runiazCiazaddr); 
anerror :- setdirCleunchpath, glo- 
bals); 
if anerror = noErr then 
BlockMove(C8thename, 
PtrCcurappname), 32); 
end; 


end; 
( ЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖХЖХЖХЖЖХЖЖЖЖЖЖЖАЖЖАЖЖЖЖЖ 


initglobals 


Initialize global data. Note that we preserve the value 
et "ieznotify^; if the current application has installed a 
routine there, we will want to run it before we run ours. 

Also, we don’t want to confuse the new application with 
the old applications’s data files, so we clear the finder 
files. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
procedure initglobals 

(globals : wpointer); 


var 
thepointer longpointer; 
nessage integer; 
count : | integer; 
index : integer; 


begin 
setglobalClong(globals2); 
with globals^ do begin 
sysdir := systemdir(globals); 


thepointer 
‚= longpointerCiaznotify); 
jazaddr :- thepointer^; 
launchaddr 
‚= BitAndClong(@post launch), 
$FFFFFF); 
end; 
CountAppF iles(message, count); 
for index := 1 to count do 
ClrAppFilesCindex2; 
end; 
(ЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖАЖЖЖЖЖЖЖЖЖХ) 


end. 


(ЖЖЖЖ) 
/codetype PACK - 15871 ‘Transfer HD’ 16 
раскћега 

раск 

pas$library 

macintfglue 

/end 


XXXXXKKXYXXXXXXXKXXXXXXXXXXKXKKXKXXXXKXXKXXXKXXXK 
rsrc.r 


(c) 1987, 1988 Attic Software 


resources for Transfer DA 


є MH HM HM * % 


XXXXXXXXXXXXXXKXX1X1XX1XX1XXXXXXXKXKXKKXXXKXXXXX 


Transfer 3.2 HD 
DF ILDMOV 


include drvr 
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include pack 


ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


* Menu resource 
KXKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKEK 


type MENU 
2715871 (4) 
Transfer 
About Transfer... 
Rebuild menu 
(- 
Finder 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
x 

* Error messages 

x 
ХХХХХХХХХХХХХХАХХХХХХХХХХХХХЕХХХХАХ ХХХ 


Туре STR? 

‚715871 (32) 

4 
I^m uneble to load the Transfer DA. 
Error building the menu list. 
Error opening the “Transfer Data" f ile. 
Error restoring the volume. 


ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
x 


x About information 
x 


ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Туре INFO=GNRL 
Тгапз, - 15870 (32) 


Transfer 3.2 HD adds а Transfer menu ++ 
to anu application that ++ 
supports desk accessories. It is ** 
intended for use with your ** 
hard disk, and 
‚5 
expects that you are using ++ 
HFS.VODVODTransfer 3.2 HD was ++ 
written by Clifford Story of ** 
Attic Software. \00\00 
‚25 
Attic Sof tware\@D++ 
P.0. Box 246054004: 
Jacksonville, ** 
Florida 32241 


ЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
x 


x Item lists 
x 


ЖЖЖАЖЖЖЖЖЖЖЖАЖЖАЖЖАЖЖЖЖЖЖХЖХЖЖАЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖХЖ 


Туре DITL 
Error ,- 15871 (32) 


ж 1 

BtnItem Enabled 
116 83 136 173 
OK 


* 2 

statText Disabled 

10 10 106 246 

“O° 1\00\00Тгапѕѓег HD error ^2,** 
\@DSystem error ^3. 


About, - 15878 (32) 
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2 

х | 

BtnItem Enabled 
252 201 272 291 
OK 


x 2 
userItem Enabled 
10 10 242 482 


Build,-15869 (32) 


* 1 

statText Disabled 

10 10 90 246 

Trensfer is building the menu list. ++ 
This will (әке 30 seconds ** 

or So but the list will be preserved ** 
and won't have to be ++ 


re-built unless you re-arrange your ++ 
disk. 


Delay, -15868 (32) 


* | 

BtnItem Enabled 
68 83 88 173 

OK 

ж 2 

statText Disabled 
10 10 58 246 


“^0” will Бе launched when you quit ++ 
this epplication. 


ЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
x 

х Dialogs 

x 
ЖЖЖЖЖЖЖЖХАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Туре 0106 
Еггог,-15871 (32) 

Transfer HD 

64 128 210 384 

invisible nogoawag 

0 

0 

- 15871 


About,-15870 (32) 
Trensfer 3.2 HD, € 1987, 1988 ++ 
Attic Software 
50 10 332 502 
invisible nogoaway 
0 
0 
- 15870 


Build,- 15869 (32) 
Transfer НО 
64 128 164 384 
invisible nogoaway 
0 


0 
- 15869 


Delay,-15868 (32) 
Transfer HD 
64 128 162 384 
invisible nogoaway 
0 


Sel 


- 15868 TN 


© The Definitive MacTutor, Vol. 4 


Advanced Mac'ing 
ТАС Driver Demo in MPW С 


The Great IAC Sample Editor!! 
(or a reasonable facsimile thereof...) 
Frank Alviani 


I had just crawled out of my sickbed and back to work. After 
getting the IAC Driver article to Dave Smith at MacTutor in the 
nick of time (as usual), wrestling with thousands of lines of 
Pascal was starting to look like a little rest - when who calls but 
our beloved assistant editor, Kirk. 

*How's the next article coming, Frank? Gonna have it ready 
in time - maybe even a little early (wistful sigh)?" "No problem, 
Kirk", I assured him; I had already set aside the evening of the 
deadline to get it written. I would have preferred to be out dancing 
with Shellie and Alice like Paul, but an editor's gotta do what an 
editor's gotta do.... 


Before continuing with the actual meat of this article, please 
understand that I assume you have read (and hopefully under- 
stood) the previous IAC articles (in the August and October '88 
issues of MacTutor). If you haven't, I’m afraid this is going to be 
quite incomprehensible... 


The IAC Sample Editor was written to demonstrate how to 
implement most (though not all) of the capabilities provided by 
the SAWS IAC driver. I chose to use a text editor for the same 
reasons many others have chosen to write sample text editors - 
TextEdit handles the surprisingly groaty details of handling the 
characters, allowing me to concentrate on the other aspects of the 
application. It handles a few small “frills”, such as choosing fonts 
and text sizes, because those are almost free; more complex 
enhancements such as scrolling have been left as “ап exercise for 
the student". THE CRITICAL MATERIAL IS THE IAC 
HANDLING, NOT THE TEXT HANDLING. /Window updat- 
ing of the displayed text could use some work, but since we have 
published fully functional text editors in the past, the reader is 
referred to those articles for improvements to the text editing 
portion of the program. For purposes of this article, the ability 
to link documents betweeen two of these editors running together 
is what is important. A change in the linked text in one document, 
causes the linked text in another document to change automati- 
cally, thus creating integrated application software between two 
independent applications! -Ed] 

Like most software, this sample editor is not 100% perfectly 
debugged (my employer has this delusion that I should be 
producing code for him during the day rather than debugging 
software for MacTutor), but all the important pieces are reasona- 
bly functional. The functions that are known to have holes are: 

1) Auto-linking between two previously linked documents 
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Frank Alviani 
Contributing Editor 
Waukegan, IL 
MacTutor Vol. 4 No. 11 


MacPaint MacDraw 


is somewhat unreliable. Alternative methods of accomplishing 
this are discussed. 

2) Identification of source and target extents in the “Links” 
menu is occasionally reversed. 


Changes To The IAC Driver 


During the course of debugging this sample editor, the 
"Complete Dependency” routine was found to be excessively 
complex and slightly buggy. After revision [found on this 
month’ s source code disk, -Ed], the rules it follows for handling 
slot-IDs are much simpler: 

1) Until adocumentregisters as a data source, its slotis filled 
with a “dummy” value of 1 to hold its place and indicate “target 
only” status (it doesn’t have a document ID yet). 

2) When a target document does register as a data source, its 
slot is refilled with its assigned document ID. 

In practice, this change would have very little effect on 
writing an application. The only real difference is that itis always 
a good idea to start a session with a slot-ID of 0 and let the IAC 
driver assign a slot, rather than trying to re-register under a slot- 
ID from the previous session. 


Basic Additional IAC Necessities 

The fundamental additional task facing an application using 
the IAC driver is that of keeping track of its data extents. You, as 
the source of data to other programs, must monitor each source 
of data in your document(s) and write any changed extents to the 
driver for the use of your client applications. 

A change in a data extent can involve 2 factors: the contents 
of the extent, and its “size”. Monitoring changes can vary widely 
in complexity, where most of the complexity involves monitor- 
ing the “size” of the data extents. For example, in an object- 
oriented graphics program such as MacDraw, the “size” of a data- 
extent (a graphic object) is unlikely to change under most 
circumstances, and so involves rather little effort to maintain 
normally. On the other hand, almost any operation in a text- 
processor is likely to change the size of an extent, and therefore 
involves quite a bit of effort to keep up-to-date. 

Since most programs are at least as interested in using data 
as in generating it, you are likely to also be a client (or dependent) 
of one or more other programs. In this case, it is your responsi- 
bility to check with the driver periodically to see if any data 
sources you depend on have changed, and to down load the data 
if they have. You need to maintain the link “targets” so that they 
can be updated as new information becomes available. 

Let’s spend a few moments looking at how some basic tasks 
are done: 
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Checking for Updates - A client program is expected to 
periodically poll the IAC driver to determine if any of its source 
extents have been updated. Being a periodic action, this naturally 
fits into the main event loop. I recommend doing it during null- 
event processing, since you aren't interfering with other activity. 
A possible concern with this approach is that of loading down the 
system by continuously polling the driver, and slowing down the 
normal response time; in the sample editor, this polling is done 
only at 1 second intervals. The only negative to this is that there 
can be up to 1 second before client applications respond to an 
update. 

Determining when to update the IAC driver - this is the 
server's side of the cooperation required. In the sample editor, I 
decided that the user would find the time needed to update the 
driver between keystrokes interfering with its usability, so the 
driver is updated only when you leave an extent [Note: in this 
version, only clicks outside an extent are checked - an extension 
for the future would be to also check the arrow keys.] In some 
applications (such as areal-time mail system) 1 update/keystroke 
might be exactly what is needed. 

The ideal to strive for is to update the shared data as often as 
possible without sending meaningless intermediate data and 
without spending excessive time during the update process. 
Transmitting each digit to a spreadsheet as it is typed, for 
example, would be undesirable since recalculation might very 
well be triggered for each keystroke, rather than at the end when 
the entire number is sent. 

Maintaining Extents - The simplest approach seems to do 
this on the fly. As mentioned above, changes to either the 
contents or the “size” of an extent need to be recorded. The 
sample editor in fact simply assumes that if you are leaving a 
source extent then you were probably doing something in it, and 
updates the driver. А more sophisticated approach would be to 
maintain a "dirty" flag foreach extent, and update the IAC driver 
only if it was true. 

Any operation that can affect the “size” of an extent deter- 
mines the amount of change and adjusts the extent accordingly. 

Providing a User Interface - In keeping with the visual 
nature of the Macintosh, there should be a visual method of 
making and displaying links between documents, that is consis- 
tent with the user interface guidelines Apple has developed. 
Simply typing ina starting and ending character position ina text 
editor, for example, is utterly unacceptable. The “magic clip- 
board" metaphor - aclipboard between applications that updates 
itself without intervention from the user - provides a logical 
extension that can be further developed. 


User Interface Implementation 

Most of the user-interface aspects of the IAC were imple- 
mented using menu commands. I chose this approach because it 
is familiar to all Mac users and independent of the application 
type. 
All commands for starting and completing dependencies 
were placed on the Edit menu, since I am using the “таріс 
clipboard" metaphor to make inter-application communications 
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seem more familiar to the user. The “kill link” command is on the 
Edit menu simply because it is the location most of us would 
expect. 

The method for displaying the location of IAC links is 
modeled after that of MPW: a menu with 1 menu item for each 
link in the document. The menu is not created until the first link 
exists. This approach was taken for several reasons. The most 
important implementation reason was that the ROM TextEdit 
package doesn’t support discontinuous selections - if it did, a 
discontinuous selection together with an alternate highlighting 
routine would be terribly simple and could show all links at once. 
Lacking that, the menu seems familiar and straightforward; the 
only non-obvious detail is that the link will remain highlighted 
until the first mouse click. 

A dialog box is used by the “Show Link Info” command to 
show the results of a census call, to find all the dependencies 
currently recorded by the IAC driver. Only the information 
returned by the census (document ID, hat check, and edition) is 
displayed; “size” and content info is likely to be incomprehen- 
sible to most applications other than the originator. 


Fundamental Data Structures 

In addition to the algorithms all programs implement, the 
other critical issue in programming is the selection of data 
structures. In an application supporting the IAC driver, 2 addi- 
tional data structures need to be implemented beyond those 
needed for the application’s work: a table of entries for each data 
extent (simply called the extent table from now on), and a small 
group of items that apply to a document as a whole, rather than 
to any particular individual extent. 

Each entry in the extent table holds the “location” or “size” 
of the extent so that the application can determine when its 
contents have changed; how this is done is totally application- 
dependent. This "location" is also necessary so that you can 
determine when the user is entering and leaving an extent; as 
mentioned above this is important in deciding when to update the 
IAC driver. It is critical to record the source document. ID of an 
extent in order to know where you are the source or a target, and 
to identify the extent to the driver. The hat. check is also needed 
for identification. The last edition read of the extent is also 
needed so you can be sure to request its successor. A "dirty flag" 
would be a useful extension to further optimize sending data to 
the driver. 

A certain amount of data needs to be kept about the docu- 
ment as a whole. This includes the slot, ID for the document, the 
document ID, the number of extents for the document, and a 
handle to the extent table (although an application that would 
never handle more than one document could make the extent 
table a global data structure rather than allocating it on the heap). 


Program Structure and Style 
The IAC Sample Editor was developed in MPW C using 
MPW 2.0.2 on a 1-Megabyte MacPlus. This was done both 
because my development environment at home is identical to my 
environment at work, and because I am generally quite happy 
with MPW (with one caveat mentioned below). 
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The source code for the sample editor is broken into а 
number of files, for several reasons. The first reason is philo- 
sophical: working with a number of small, well-named files is 
much better when it comes to maintaining code. The second 
reason is pragmatic: this approach usually results in faster devel- 
opment, since far less of the source is processed when a change 
is made. The final reason is also pragmatic: it was the only way 
I could get the sample to build on my 1-Meg machine at home. 

This brings up the caveat about MPW mentioned above - its 
memory appetite. The amount of memory needed for the C 
compiler seems rather excessive (especially compared to the 
Pascal compiler), and the overall requirements for MPW are high 
(1300K under MultiFinder, for example). While I am painfully 
aware of how much effort can be required to squeeze programs 
into smaller spaces, the cost of RAM is unlikely to drop a great 
deal in the near future, and requiring people to have 2-4 mega- 
bytes of RAM to use MPW 3.0 with source level debugging 
borders on arrogance. (End of tirade...) 

Since this program was explicitly written as a sample to 
demonstrate how to use the IAC driver, it is somewhat more 
verbose than the traditional C program. I am convinced by 
experience that well-chosen names can be critical to the readabil- 
ity of code in any language, and try to write code that conveys as 
much meaning as possible at first glance. The argument that “С 
is a terse language" is simply concealed laziness; the slight extra 
effort involved in typing longer names will be repaid many times 
when you are debugging a routine, it is no longer fresh in your 
mind, and you don't need to rummage around in many different 
source files to try and recall what those obscurely name variables 
are really being used for. 

Please note that the IAC routines are careful to return error 
codes for the use of the application. While this sample doesn't 
check them extremely thoroughly (nor does it check the ROM 
routine error codes as well as it should), a real applications should 
be paranoid about problems and pay attention to them! 

The sample editor currently will support only 1 window. 
However, in order to simplify extension to multiple windows, all 
information relevant to an entire document (rather than just to 
individual extents) is maintained in a relocatable block whose 
handle is kept in the wRefCon field of the window record. It 
should not be very complex to extend the editor to properly 
support multiple windows. 

The source files that make up the IAC Sample Editor, and 
their uses, are as follows: 


Editor.b The MPW script that controls the building 
process. 

Editor.m The input to “Маке” that describes the de- 
pendencies between source files, and how to 
build any part of the Editor. 

Editor.h Globals and common definitions. 

. IAC.h Definitions for the IAC interface package. 

Editor.c The mainline, and the extent-maintaining 
routines. 

Editor.r The Rez input file. 

Boxes.c Code for displaying the dialog boxes, includ- 


ing the census information. 
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Doc rtns.c Code for document management - open, close, 
save, etc. 
Edit ТАС rtns.c Code for implementing “Hot Copy" and "Hot 


Paste" operations. 


Edit rtns.c Code for implementing the standard text edit- 
ing functions, with extensions for extent main- 
tenance. 

IAC.c The interface package to the IAC driver. 

SysEnvs.a Glue for the SysEnvirons call. 


While it would be tedious to read (and write!) a detailed 
description of every function in the program, certain functions do 
merit examination, since they demonstrate methods for using the 
IAC driver. Let's take a closer look at these routines. 


Extent-maintaining Routines 

The operations necessary to maintaining extent information 
have beencollected into a group of routines which are in the main 
file Editor.c These are as follows: 

chk extent: This routine is used by all the other extent- 
maintaining functions. In this text editor, an extent is defined to 
be a character range (in others it could be a paragraph, for 
example). If the current selection overlaps an entry in the extent 
table, that extent is made the current extent. We check the current 
extent first, as a small optimization to try and avoid processing 
the entire extent table. In any case, we return a boolean that tells 
if we are now in an extent. 

One limitation in this implementation is that it does not deal 
with a selection range that spans extents. In a real application an 
extent very likely would be a significant amount of data (rather 
than a single word, for instance), and a selection would be much 
less likely to span extents. 

Thisisafunction thatis very application dependent, and will 
vary a lot in implementation, since the tests for a graphics 
program is utterly different from those for a text program. 

ext move: This is the routine that determines if the user has 
left the current extent, and updates the IAC driver if he/she has. 
If the selection is no longer in the original extent and that extent 
was a "source" extent (one for which we are sending data to the 
IAC driver), then we write the latest contents of that extent to the 
driver. We have nothing to do if weare transferring intoan extent, 
or if the extent we are leaving is a "target" extent. 

This does not maintain a "dirty" flag for each extent, and 
assumes that any source extent you are leaving has been changed, 
writing its data to the driver automatically. Maintaining a dirty 
flag for each extent (as well as for the document as a whole) 
would allow this routine to minimize traffic to the IAC driver. 

ext write: This routine is responsible for writing the con- 
tents of an extent to the IAC driver. It sets up a private buffer into 
which the data size, constant format of ‘TEXT’, and the data are 
written, and then just calls the interface routine iac write, data. 

ext read: Thisroutineisresponsible forread the contents of 
an extent from the IAC driver. It automatically asks for the 
successor to the last extent read, and updates the extent with the 
edition actually returned by the driver. The selection range of the 
extent is selected and replaced by the new data from the driver. 
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If there was а change in the size of the extent, the extent is 
updated. 
IAC User-Interface Routines 

These are the routines that are the user’s actual interface to 
the IAC driver. They are as follows: 

do hotCopy: This is the routine that establishes a “source” 
link. The first step is to check to see if we are already in an existing 
dependency; if we are, an alert is issued to the user pointing out 
that error, and we quit. Normal processing is to call 
iac_add_dependency to add an entry to the driver’s dependency 
table. Since source documents are issued document IDs, this 
updates the doc_ID field of the window data block. Since the 
slot_ID field can be updated by the driver, it is also updated by 
this routine. A new entry is added to the table of extents associ- 
ated with the document. 

After the dependency has been successfully started, this 
routine also calls ext_write to send the initial copy of the contents 
of the extent to the driver (we assume that creating a link implies 
that another program will be immediately interested in the 
contents). 

In order to give the user some way of viewing the links 
established between documents, add_display_cmd is called to 
add the newly established dependency source to the “Links” 
menu. 

do_hotPaste: This is the routine that completes a link. Like 
do_hotCopy, the first step is to check to see if we are already in 
an existing dependency; if we are, an alert is issued to the user 
pointing out that error, and we quit. Normal processing is to call 
iac_complete_dependency. We do not update the document ID 
field since the document ID returned by the driver is that of the 
source document. Since the slot_ID field can be updated by the 
driver, it is updated by this routine. A new entry is added to the 
table of extents associated with the document. 

After the dependency has been successfully completed, this 
routine calls ext_read to read the initial copy of the contents from 
the driver. 

In order to give the user some way of viewing the links 
established between documents, add_display_cmd is called to 
add the newly established dependency target to the “Links” 
menu. 

The two IAC routines use different algorithms for adding a 
new entry to the extent table, which was done for a reason. In 
some applications, the ordering of extents may not be important; 
do_hotCopy makes this assumption and just adds another extent 
to the end of the table. In other applications (such as a text editor) 
the order may be more relevant; do_hotPaste inserts a new entry 
so the starting locations of the extents are in ascending order. In 
this text editor, this means that only an extent and its successors 
need updating, rather than having to process the entire table. In 
a real application, of course, you need to take a consistent 
approach to maintaining the extent table. 


Text Editing Routines 
These perform the normal TextEdit functions, with the 
addition of the IAC code. Since development time was stretching 
out well beyond expectation, only the routine do_key actually 
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updates extent-size information, but all of the routines that need 
to do so have the skeleton code in place, and all of them do 
actually communicate with the IAC driver. 

do_clear: This uses the normal TEDelete call to the ROM to 
remove text without placing it on the clipboard, after calling 
chk extent to see which , if any, extent is being affected. If an 
entire extent was cleared, iac remove, dependency is called, 
otherwise iac_write_data is called to provide the latest data to the 
driver. 

do_copy: This does nothing at all with the IAC driver, since 
it doesn’t affect the data! 

do_cut: The processing here is virtually identical to that in 
do_clear, except that TECut is called instead. 

do key: We check to see if we are in an extent (chk_extent), 
and then call TEKey to actually insert the character into the text. 
If we were in an extent, we only need to adjust the end of the 
extent. If a backspace was processed, we decrement the end, 
otherwise we increment it. 

do_paste: This is very similar in processing to do_key. If we 
were in an extent, the end of the extent is incremented by the 
amount of text inserted. This is actually an oversimplification, 
since it doesn’t take into account text replacement. 


Document Maintaining Routines 

These perform all the traditional file-system functions, with 
the addition of saving and restoring IAC information needed for 
the convenience of the user. They are not in alphabetical order: 

setup wind: This is а common routine is used to set up the 
window and initialize the extent table and window data struc- 
tures. 

save doc: In addition to the normal function of writing the 
data toa file, creating it if necessary, this must also save the extent 
table and the document-wide data for future usage. This informa- 
tion is stored in resources of type ‘EXTN’; if we are saving an 
existing file, previous resources are removed before writing the 
new versions. 

open doc: While opening a document is often a complex 
process due to the application's data structures, in the sample 
editor the complexity is due to the (optional) process of trying to 
reconnect any links that may have existed to already-open 
documents. This is half of the reconnection process; the other 
half, of having an open document reconnect to a just-opened 
document, would be a function of poll iac. 

The functions of this routine divide neatly into several parts: 

(1) read the text data from a user selected file and create a 

window for it. 

(2) retrieve the extent table and some of the document-wide 

data and attach them to the window. 

(3) once these have been retrieved, try to re-establish any 

links that had existed previously, with already-opened docu- 

ments. This is done as follows: 

a) Issue an iac. census call to determine the current state 
of the universe. Assuming the call is successful and there are 
already documents that have posted their source dependen- 
cies, 

b) Check each entry in the census against the extent table. 
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If a census entry matches an extent: 

i) issue an iac available dependency call to setup the 
linkage, 

ii) issue an iac. complete dependency call to complete 
It, 

iii) issue an ext_read call to get the latest copy of the data 
from the driver, and 

iv) call add_display_cmd to add the dependency to the 
user’s “Links” menu. 

c) Now that as many as possible of your target extents are 
linked up again, it’s time to post your source extents to the 
IAC driver. This is a simpler process, since it isn’t necessary 
to match the census info against the extent table. For each 
extent just: 

i) If you are the source for the extent, call 
iac_add_dependency to post the extent to the IAC driver, 

ii) call ext_write to copy the latest version of your data 
up to the driver, and 

iii) call add_display_cmd to add the dependency to the 
user’s “Links” menu. 


This is one approach to reconnecting documents that were 
linked in a “previous life”. The other approach is roughly 
equivalent in complexity, but moves part (b) in the description 
above to poll iac. Open doc simply posts all of its source 
extents, and poll iac recognizes any new sources that appear 
during a census. When a new source document appears, it then 
reconnects. 


Other Routines 

These serve important functions, but don't fit neatly into the 
other categories. They are as follows: 

poll iac: Thisisresponsible for automatically downloading 
updated data from the IAC driver. It checks at 60-tick (1 second) 
intervals to balance timely updates against system traffic. 
iac, status is called to see if any changes at all have occurred. 

There are several strategies that can be used to ensure that all 
updated links are read. The approach used here is simply to try 
and read every link for which it is a target, relying on the driver 
to ignore any extents which haven't been changed. Another, 
probably more efficient tack, is to make an iac. census call first. 
You would then check the edition of each source link against that 
stored in the extent's record, and only try and read those which 
you know have changed. The trade off is in the (slightly more 
complex) processing required for the census call against the 
(simpler) unnecessary read calls. 

An extension mentioned above that can be added to this 
routine is to check the data returned by the iac, status call to see 
if a new document has added dependencies to the driver. If one 
has, you can then make an iac census call to check the new 
entries against your extent table; should any of them be sources 
for your target links, those links can be re-established without 
further intervention. This is needed if an open document is to be 
able to re-link to a document opened after it. 

link display: This is used to highlight an extent. It uses a 
tiny assembler routine to implement an alternate highlighting 
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routine as (obscurely) documented in the TextEdit chapter of 
Inside Macintosh. The routine is installed, and the extent range 
selected, which invokes our highlighting routine (which uses 
exclusive-or mode for reversibility). We then check the mouse 
button in order to wait for a mouse click to indicate the user is 
done, and reselect the original range (which calls ош routine, 
which undoes the highlighting). Finally, the hook in the TE 
record is removed to restore TextEdit' s normal behavior. 

The only small difficulty came in getting the assembler 
routine linked in with the rest of the application. It turns out to be 
necessary to have the assembler's case option set to OBJECT so 
that the procedure label is written to the object file with the proper 
case (C is case sensitive), but to allow case-insensitivity for 
references to equate files. Sigh... 


Debugging Concerns 

Debugging under MultiFinder is slightly different than 
debugging under the normal Finder, primarily due to the ease 
with which you can get “lost” in memory. The latest version of 
TMON (2.8.1- which is what I always use for debugging), for 
example, has no facilities for dealing with multiple application 
zones. This is not the end of the world, however. 

The primary tool at your disposal is attention: you must pay 
closer attention to the application zone than under the single- 
application system, since the only way to tell zones apart is by 
their address ranges. Fortunately, all of your regular debugging 
tools still work, and context switching occurs only at well- 
specified times, so life really isn't too bad once you get used to 
things. 

The symbolic-debugging ability of TMON is virtually in- 
valuable, and requires one small change to the normal C compi- 
lation. The “-g” option is required to have the MPW C compiler 
insert the stack frames and routine names needed by TMON, 
since the normal code generated doesn't require or use them. 

Itis often useful to set breakpoints in several applications at 
once. TMON supports this with no difficulty; the only trick is to 
be absolutely certain of which application is in the foreground 
when you set the breakpoint. I often start setting breakpoints in 
one program from the left end of the window, and breakpoints in 
the other program from the right end; this can sometimes make 
it a little easier to tell what's going on. 


Final Notes 

This has turned out to be a far larger piece of cake to chew 
than either Paul or I originally anticipated (merely proving again 
that all programmers are optimists, or we never would have 
gotten ourselves into all this...) and has also turned out to be very 
educational, to say the least. While this is the last article on the 
IACI will be writing for a while (Iam in the middle of massively 
renovating my house as this is being written), at least one more 
article that Iknow of should be appearing in the near future. Once 
my brain has cleared somewhat, there are several non-obvious 
extensions that can be implemented even with the driver in its 
current state, and a number of people have already discussed 
adding inter-machine communications. The future should be 
most interesting. 
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I cannot end this escapade without expressing my deepest 
gratitude to my infinitely-patient wife Alice, who has put up with 
atired 1-yearold by herself far too many times while I was up into 
the early morning trying to wring bugs out of stubborn code. 


Listing: Editor.b 
"ua Editor.b - Build the sample editor 
н 


8 Usage: 

8 Set exit [Ø | 1); 

8 [f exit == 0, all compiles and assemblies will be com- 
pleted. If апу errors occur, subsequent steps will be 
Skipped. If exit == 1, the procedure stops after the first 
error occurs. 

н 

8 Set hixSre “source directory’; Export Һ165гс 

8 Set hlxEtc “result directory”; Export hlsEtc 

8 Set hIixProg “auxiliary program’; Export hlsProg 

8 ] general.b [ -r | -m] (makeParans..] 

8" -r Repeat previous build, using existing 

* (h1xEtc)mekeout^. (Actually, this option merely suppresses 
the "makeout^ creation.) 


8 os Must be the first Cand only) parameter. 

8 " -m Make *(hlxEtc)maekeout^, but do not execute it. 
яя Must be the first parameter. 

н п makeParams Additional parameters to make; e.g.: 

"os -d prz^-p^ Report progress 

88 -d e="8” Suppress log detail 

88 -е Make everything. 

88 =t Merely touch dates to bring everything up- 
to-date. 


open “(109)” 
"open “(worksheet)” 
echo ‘Date -a -t’ ‘Date -s -d' Start (hlxA1t) >> “(109)” 


cd *(hixSrc)^ 
set result Done 
if *(1)^ == *-n* 
set result Made 
shift 1 
end 
if “(1)” 7%) -г” 
If (result) == Done 
echo set err 0» “(hIxEtc}makeout” 
unset err 
make (“parameters”) -f (hixprg).m >> *(hixEtc)makeout^ 
end || Set result Failed 
end 
if (result) == “Done” 
“{hlxEtc}makeout’” || Set result Failed 
end 
echo ‘Date -a -t' ‘Date -s -d' (result) >» “(log)” 
(MacAppDone) 
exit 1 If result == Failed 


Listing: Editor.n 
# Маке file for the Sample IAC-friendly Editor 


ob = (hixEtc) "Set these definitions to your normal working 
directories 

sr = (hixSrc) 

prog = (hix) 

e = echo 


COptions = -o (ob) -g -q2 
AOptions = -i (mpw)AIncludes -o "(ob)" 


*(prog)Editor" f Editor.r (ob)Editor.code 


(e) ‘Date -a -t’ Rez Editor >> “(100)” 
Rez Editor.r -o *(prog)Editor^ -t APPL -c IACI 
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Setfile -a b “(prog}Editor’ set bundle bit 


(ob)Editor.code f (ob)Editor.c.o (ob) IAC.c.o à 
(ob)SysEnv.a.o (ob)Doc.rtns.c.o à 
(ob)Edit IAC.rtns.c.o (ob)Edit.rtns.c.o д 
(ob)Editor.a.o (ob)Boxes.c.o 


exit 1 if (err) © 0 


(e) 'Date -a -t' Link Editor »» “(104)” 
(ob)IAC.c.o  (ob)SysEnv.a.o д 
{ob}Doc_rtns.c.o (ob)Edit IAC.rtns.c.o 


Link (ob)Editor.c.o 


(ob)Edit. rtns.c.o д 
(ob)Editor.a.o 


(ob)Boxes.c.o д 
* (CLibreries)"CRuntime.o à 

* (CLibreries)^CInterface.o à 

* (CLibreries)"StdCLib.o д 

* (CLibraries)"CSANElib.o à 

* (Libraries) ^Interface.o д 

-t “OBU " -o (ob)Editor.code 


(ob)Editor.c.o f (sr)Editor.c (sr)IAC.h (sr)Editor.h 
(e) “Date -a -t' C Editor >> “(100)” 
C (COptions) Editor.c || set err 1 


(ob)IAC.c.of (sr)IAC.c (sr)IAC.h 
(e) “Date -a -t° C IAC >> “(log)” 
C (COptions) IAC.c || set err 1 


(ob)SysEnv.a.o f (sr)SusEnv.a 
(e) ‘Date -a -t' Asm SysEnv >> “(100)” 
Asm (A0ptions) SusEnv.a || Set err 1 


(ob)Editor.a.o f (sr)Editor.e 
(e) “Date -a -t' Asm Editor.a >> “(104)” 
Asm (A0ptions) Editor.a || Set err 1 


(ob)Doc.rtns.c.o 
(sr)Editor.h 


f 


(sr}Doc_rtns.c (sr)IAC.h 


(e) “Date -a -t' С Doc.rtns >> “(log)” 
С (COptions) Doc.rtns.c || set err 1 


{ob}Edit_IAC_rtns.c.o f 

(sr)IAC.h (sr)Editor.h 
(e) “Date -a -t' C Edit IAC rtns >> “(log)” 
С (COptions) Edit IAC.rtns.c || set err 1 


(ob)Edit rtns.c.o 
(sr)Editor.h 


f 


(sr)Edit.IAC. rtns.c 


(sr)Edit. rtns.c (sr) IAC.h 


(e) “Date -a -t' C Edit.rtns >> “(log)” 
С (COptions) Edit.rtns.c || set err 1 


(ob)Boxes.c.o 
(sr)Editor.h 


) 


(sr)Boxes.c (sr) IAC.h 


(e) “Date -a -t' C Boxes >> “(log)” 
C (COptions) Boxes.c || set err 1 


Listing: Editor.h 
/* 


* Resource ID constants. 
*/ Š 


8 define appleID 

8 define fileID 

® define editID 

® define optionsID 

Я define fontID 

я define sizeID 

* define linkDisplayID 


128 
129 
130 
131 
132 
133 
134 


/* MyMenus(] array indexes */ 


8 define appleMenu 


Я define fileMenu 
8 define newCommand 


Ü 
* define aboutMeCommand 1 


1 
1 
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8 define openCommand 
# define closeCommand 
# define saveCommand 
8 define quitCommand 


C > GW м 


t define editMenu 

я define undoCommand 
я define cutCommand 

* define copyCommand 
* define pasteCommand 
8 define clearCommand 


C Ol & G) м 


/* The IAC Commands!! */ 

* define hotCopyCommand 8 
8 define hotPasteCommand 9 
8 define zepLinkCommand 10 


* define optionsMenu 3 
8 define showLinksCmd 1 
8 define showLinkInfoCmd 2 


def ine fontMenu 
def ine sizeMenu 
define linkdDispMenu 
def ine menuCount 


зини 
NOON > 


/* windows, dialogs, and alerts */ 
8 define windowID 128 
8 define ABOUT. DLOG 128 
я define ABOUT. LINKS 129 
8 define NO. IAC 256 
я define ТАС. ЕКЕ ALRT 257 
8 define NOT. ІМ ЕХТ 258 
8 define KILL_EXT 259 
8 define SAVE CHANGES 260 


8 define BS 0x08 
# define POLL_INT 60 
8 define SLEEP 20 


/* Formats supported by IAC driver, normal resource types */ 
* define ТХТ_РМТ 0х54455854 


/* Error codes returned by the IAC driver */ 
define М0. МОКЕ. 0065 -2000 

def ine NO MORE. 510Т5 -2001 

define WRITE FAILED -2002 

define MISSING.LINK -2003 

define NO_NEWER_ED -2004 

define READ FAILED -2005 

8 define М0. 5УСН. ПЕР -2006 

8 define 010. КОМ5 -2007 


t$ 3$ 31$ 2 3$ 3 


/* 


*Information records associated with a window 
х/ 


typedef struct ( 
long src-doc; 
short X hat check; 
short ей level; 


/* doc ID of source doc */ 

/* identifier for an extent */ 

/* edition for extent */ 
short — ext.strt; /* start of extent range */ 
short ext. end; /* end of extent range */ 

) extent, *extentP, *exTable, **extentH; 


typedef struct ( 
short the_slot; 
long  doc.ID; 
short ext cnt; 
short relevent; 


/* slot. ID for this document */ 

/* document ID for this doc */ 

/* number of extents with this doc */ 
/* 8 un-updated extents */ 


extentH the_extents; /* block of extent records */ 
TEHandle wind. TEH; /* TEHandle for this window */ 
Boolean dirty; /* doc needs saving */ 


String(63) doc_file_nm; /* if null, never been saved */ 
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) win_data, *win dataP, **win. dataH; 


/***x 


х Global Data objects, used by routines external to main(). 
xxx / 


tifndef PUBLIC 
def ine PUBLIC 
#undef NO. INIT 
else 
#def ine NO. INIT 
Üendif 


PUBLIC MenuHandle X MyMenus[menuCount]; /* The menu handles */ 


PUBLIC Boolean DoneFlag; /*true when File:Quit chosen */ 
PUBLIC TEHandle TextH; /* The TextEdit handle */ 
PUBLIC CursHandle — ibeamHdl; 

PUBLIC WindowPtr — myWindow; /* the text window */ 


PUBLIC WindowRecord ^ wRecord; 
PUBLIC win. dataH the. data. H; 
PUBLIC short fRef ; 

PUBLIC short 


/* store the window stuff */ 
/* data for а window */ 
/* refnum for document file */ 
the fNum, the size; /Х text attributes */ 


PUBLIC Style the-style; 

PUBLIC extent curr_ext; /* latest extent worked on */ 
PUBLIC short curr_ext_no; /* index of curr_ext */ 
PUBLIC Boolean ext_active; /* an active extent? */ 
PUBLIC long last_poll; /* when we last polled IAC */ 


/*f_sizes k f styles are used іп the menu_tree() processing 
апа ere read only */ 


8ifdef NO_INIT 


PUBLIC short extent count;  /* links we are target of */ 


PUBLIC Boolean link_menu; /% link menu created */ 
PUBLIC short f sizes(8]; 
PUBLIC Style f styles[51; 


"else 

PUBLIC short 
PUBLIC Boolean 
PUBLIC short 
28); 

PUBLIC Style 
outline, shadow); 
#endif 


extent_count = 0; 
link.menu = false; 
f_sizes(8] = (9, 10, 12, 14, 16, 20, 24, 


f_styles[5] = (bold, italic, underline, 


/* 
* HIWORD and LOWORD macros, for readability. 
*/ 

8 define HIWORDCaLong) 

8 define LOWORDCaLong) 


Listing: IAC.h 


(CCaLong) >> 16) & OxFFFF) 
(Са опа) & OxFFFF) 


/*This is the set ОҒ externs needed to access the IAC inter- 
face routines. The pointer/handle indicators are only remind- 
ers */ 


extern short iac_add_dependency();/* *doc_ID, *slot_ID, 
*hat check, *edition */ 
extern short iac available.dependency(); /* doc_id, hat check 
*/ 
extern short iac_census(); /* *extent_count, **extent_info */ 
extern short iac_complete_dependencu(); /* *doc_id, *slot_id, 
xhat_check */ 
extern short iac_open(); 
extern short iac-read_data(); /* doc_id, slot_id, hat check, 
*edition, fmt_pref[], *fmt code, **ext_data */ 
extern short iac_remove_dependency(); /% doc_id, slot id, 
hat.check */ 
extern short iac_status(); /* slot_id, *vers_id, *doc_count, 
*extent count */ 
extern short iac_write_data(); /* бос. ід, hat. check, *edition, 
fnt. count, **ext data */ 
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/*error codes for iac_open, etc. */ 
8 define NO. DRIVER -1 

® define EARLY. SYS -2 

8 define МАХ. ЕХТ5 64 


typedef struct ( 
long  doc.ID; 


short ed level; 
short X hat check; 
) info.rec; 


typedef struct ( 
info.rec ext entry [MAX ЕХТ51; 
) info-tbl, *info-tblP, **info. tblH; 


Listing: Editor.a 


мы К КЕ ЖЖ 
;***** The SAWS Inter-Application Commun. Driver Sample Program 
,***** Text Highlighting Routines for TextEdit 

ужжжжх Frank Alviani - 9/88 


; ERRERRARARERERER AAAS ERAS RARE AERA ХХХ ЖЖ AAA ЖЖ 


ii 


include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 


«types.» 
«emory.h? 
«quickdraw.h? 
«toolutils.h» 
«windows .h? 
«controls.h? 
«(fonts.h? 
tevents.h? 
«dialogs.h? 
«nenus .h> 
«desk.h»? 
K(textedit.h? 
«segload.h? 
<string.h> 
«resources .ћ› 


include <iac.h> 
Я undef PUBLIC 
Я include <Editor.h> 


8#def ine noErr 0 /* 0 for success */ 


INCLUDE 
INCLUDE 
INCLUDE 
INCLUDE 
INCLUDE 


‘Тгарз.а’ 
“би1сКЕди.а^ 
‘SysEqu.a’ 
‘SysErr .a’ 
‘ToolEqu.a’ 


ex 


/* 


x 


tern DataInit(); 


x 
Routine: mainC) 


STRING PASCAL 
CASE OBJECT 


This routine highlights the rectangle passed on the stack by 
“stippling” it. There could be separate routines for*target” 
end "source^ links. Exclusive-or mode is used since this 
called twice Cselect and deselect) and we need to return the 
text to its original look. 

Input: A3 points to locked TERec 

Can destroy А0, A1, 00, 02, 03 


Cd wo w- emo 


ourceHigh PROC EXPORT 
MOVE .W *patXor, - CAT) 
-PenMode 
MOVE.L GrafGlobalsCA5), Аб 
РЕА 1tGrayCAS) ;set stipple 
_PenPat 
-PaintRect ,Stipple the text 

; -PeintRect pops rectangle off stack, leaving return address 
RT 


¿set mode 


END 
Listing: Editor.c 


/**X 
x 


x File: Editor.c 
x 


* Package: Mainline 
x 
* Description: This is the mainline for the editor program to 
test the Inter Application Communications CIAC) driver. Some 
code from the Apple “sample.c” was adapted. 
x 
* Structure: In this source the following structure is used: 
* includes & def ines 


x global variable definitions 

x main() 

x initialization routines 

* the menu dispatcher тепи_{гее() 
Ж dialog-box handlers 

x 

* Author: 

*FEA 6/88 - 7/88 
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x 
* Mainline of the test program 


х/ 
int mainC) 
short init.result; /* NULL if OK */ 
short item; /* alert button */ 
Rect screenRect; 
Rect dragRect; 
Rect txRect; 
Point mousePt; 
EventRecordmyEvent; 


WindowPtr theActiveWindow; 
WindowPtr whichWindow; 


win-dateH (һе баба Н;  /* data associated with a window */ 


extern void menu_tree(), do_key(), poll_iac(); 
extern void ext_move(); 

extern short edit init(); 

extern WindowPtr  myWindow; 


UnloedSeg(.DataInit); 
init .result = edit п О; 
if Cinit result) 


item = StopAlert(NO ТАС, nil); 
return 0; /* allow C runtime cleanup */ 


UnloadSegCedit_init); /* if we get here, IAC open */ 
/* window setup is handled by ‘new’ and ‘open’ commands */ 
screenRect = qd.screenBits.bounds; 
SetRect(&dragRect, 4, 20 + 4, screenRect.right-4, 
screenRect .bottom-4); 


/* The One True Event Loop */ 
DoneFlag = false; 
for С;; ) 
(болеҒ 18g) 
break; /% from main event loop */ 
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/* 
* Main Event tasks: 
ж/ 


theActiveWindow = FrontWindow(); 
repeated calls */ 


/* Used often, avoid 


if CmyWindow && CmyWindow == theActiveWindow)) 
( 
GetMouse(&mouseP +); 
SetCursor(PtInRectC&mousePt, &myWindow->portRect) ? 
*ibeamHdl : &qd.arrow); 
TEIdleCTextH); 


the-data.H = Cwin_dataH) GetWRefCon CmyWindow); 
( ((**the_data_-H).dirtu) 


EnableItem (MuMenus[fileMenu], saveCommand); 
else 


DisableItem CMyMenus[fileMenu], saveCommand); 


) 
if C!WaitNextEventCeveryEvent, &myEvent, SLEEP, nil)) 
( 
/ЖА null or system event! IAC polling goes here. 
We only poll if we have link targets to check. */ 
if CtheActiveWindow && extent count) 


poll_iac(theActiveWindow); 


continue; 


) 


the_data H = Cwin_dataH) GetWRefConCtheActiveWindow2; 
TextH = C**the. data. HD .wind. ТЕН; 


Qe (myEvent . what) 


case mouseDown: 
switch CFindWindowC&myEvent. where, &whichWindow)) 
( 


case inSysWindow: 
SustemClickC&myEvent, whichWindow); 
break; 


case inMenuBar: 
menu_tree(MenuSelect(&muEvent.where)); 
break; 


case inDrag: 


DragWindow(whichwindow, &muEvent.where, &dragRect); 


break; 


case inGrow: /* There is no grow box. */ 
break; 


case inContent: 
if CwhichWindow != theActiveWindow) 


SelectWindow(whichWindow); 
else if (whichWindow == myWindow) 
ext_move(&myEvent, theActiveWindow); 
break; 
default: 


break; 
)/*endsw FindWindow*/ 
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break; 


case autoKey: /* ignore command-key */ 
if (muWindow == theActiveWindow) 
( 


do_keyCmyEvent.message); /* check extents */ 
break; 


case keyDown: 
if CmyWindow == theActiveWindow) 


(nyEvent.modif iers & cmdKey) 


menu treeCMenuKey(mgEvent.message & charCode- 
Mask )); 


else 


do_keyCmyEvent.message); /* check extents */ 


) 


break; 


case app4Evt: /* suspend/resume */ 
break; 


case activateEvt: 
if CCWindowPtr) myEvent.message == myWindow) 


if CmyEvent.modifiers & activeFlag) 


TEActivate(TextH); 
DisableItemCMyMenus[editMenu], undoCommand); 


else 


TEDeactivateCTextH2; 
EnableItemCMyMenus [edi {Мепи], undoCommand); 


) 


break; 


case updateEvt: 
if ((WindowPtr) myEvent.message == theActiveWindow) 


BeginUpdate( theAct iveW indow); 
EraseRect(&theActivewW indow->por tRect); 
TEUpdate(&theActiveWindow->portRect, TextH); 
EndUpdate( theAct iveWindow); 


break; 


default: 
break; 


} /* endsw myEvent.what */ 
) /* for */ 
i Стун indow) 


/* shut down code, including “save changes?” */ 
CloseWindow(myWindow); 


return 0; /* Return to allow C runtime cleanup */ 


/** 


x Routine: chk_extent 
x 


* This routine checks the selection range in the TE record 
to determine if it intersects the current extent. If not, it 
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checks the entire set of extents to try and identify the extent 


it might intersect. If we are notcurrently іп ап exent, the 
'current extent^ structure is filled with -1s as is 
'curr.ext.no'. */ 


* define . SEG. Main 
Boolean chk_extent(TextH, the-extH, ext cnt) 
TEHendle — TextH; /* The TextEdit record to check */ 


extentH the .extH; /* handle to extent block */ 
short ext.cnt; /* how many extents to process */ 
short strt, endd; /% range in TE record */ 
short 15 /* scratch */ 
exTable ext recs; 
Boolean left, right; 


if Cext_cnt) 


strt = (**TextH).selStart; 
endd = (**TextH).selEnd; 
ext recs = *the_extH; 


/* Check last extent used. If not in that, scan entire 
table. We аге affecting ап extent if EITHER the start or end 
of the TE selection falls between the start and end of the 
extent Cinclusive). %/ 


left = Ccurr_ext.ext_strt <= strt) && (Ccurr_ext.ext_end >= 


strt); 


right = (Ccurr_ext.ext_strt <= endd) && Ccurr_ext.ext_end 


»= endd); 
if Cleft ||right? /* overlap on either end */ 


return Сігие); /* existing info alright es is */ 
else /* switched, check all */ 
for (i20; i«ext cnt; i++) 


left = Cext_recslil.ext_strt <= strt) && 
Cext.recs[iJ.ext end >= strt); 

right = Cext_recslil.ext_strt <= endd) && 
(ext_recs[il].ext_end >= endd); 

Ü (left ||right) /* this now the current extent */ 


curr_ext.ext_strt = ext recsfilJ.ext.strt; 
curr.ext.ext.end = ext recs[il.ext.end; 
curr.ext.hat. check = ext_recs[i].hat check; 
curr.ext.ed level = ext recs[il.ed level; 
curr.ext.no = i; 

return (true); 


) 
) /* end for */ 
) /* end else */ 
) /* end there-are-extents */ 


curr.ext.ext.strt = -1; /* not current in an extent */ 
curr.ext.ext.end = -1; 

curr.ext.hat. check = -1; 

curr.ext.ed level = -1; 

curr_extno = -1; 

return(false); 


) 

/** 
х Routine: ext. write 
x 


ж This routine handles the mechanics of actually writing an 


extent’s data to the IAC driver. */ 
# define . SEG... Main 


short ext writeCTextH, strt, sz, the. doc, the hatcheck, 
the. ed) 
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TEHendle TextH; /* The TextEdit handle */ 

short strt; /* position of 1st cher to write */ 
short SZ; /* count of bytes */ 

long the_doc; /% which doc */ 

short the hatcheck ; 

short *the_ed; 


( 
short iac. code; /* result from IAC call */ 
long data. size; 


Handle ехі data, t base; 
long *] ptr; /* recest to ease setting up hdr */ 


8 define — HDR. SIZE 8 


ext data = NewHandle (sz + HDR_SIZE); 

l.ptr = (long *OC*ext. date); 

*] ptr = TXT_FMT; 

*(1.ptr*1) = (long) sz; 

t Базе = (**TextH).hText; 

BlockMove (%% base + strt, 
(*ext data) + HDR_SIZE, 
(long) 52); 

1ас_соде = iac_write_data(the_doc, the.hatcheck, the_ed, 1, 

ext. data); 
DisposHandleCext. data); 
return Ciac_code); 


/* source */ 
/* dest */ 


/** 


* Routine: ext read 
* 


* This routine handles the mechanics of actuallu reading an 
extent’s data from the IAC driver. If successful the 
edition level for the extent is updated. */ 


8 define —SEG— Main 

short ext read(w.Ptr, the ed, which) 
WindowPtr w.Ptr; 
short *the.ed; — /* edition of the extent to read */ 
short which; /* which extent (хего-Базед) */ 


win_dataH the .data.H; A /* data associated with a window */ 


extentH the. extH; /* hendle to extent block */ 
TEHandle TextH; /* The TextEdit handle */ 

exTeble ext recs; /* walking extents for adjusting */ 
long fmt. code; /* actual data format from ТАС */ 


long fmt-pref [3]; /% format prefs, descending */ 
long old.st, old_end; /* TE selection before poll */ 
short delta; /* change in extent size */ 

short en ей, j; /* traditional loop counters */ 
short data. size; 
Handle — ext. date; /* Handle to data block */ 
short iac.code = noErr; /* result from IAC cell */ 


{Не_да{а_Н = (win_dataH) GetWRef ConCw. Ptr); 
TextH - (**the. data. H5 . wind TEH; 
the. extH = C(**the. data. HD. the extents; 


fnt ргеҒ((01 = ТХТ. ҒМТ; 

(ті. рге” [1] = Ø; 
HLockCthe-extH2; 

ext recs = *the.extH; 

ext. data = NewHandleCOL); 
/* need memory test here */ 


әп ей = *the_ed + 1; 
iec.code = iac read. dataCext recs[which].src. doc, 
(**the. data. Н). the. slot, 
ext recs[which].hat check, 
бәл. ed, 
&fmt_pref [0], 
&fmt. code, 
ext_data); 
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if Сіас_соде == noErr) 


ext recs[which].ed. level = an.ed; /* update extent */ 
*the_ed = an. ed; /* update caller */ 
data. size = GetHandleSizeCext data); 


delta = data. size - Cext_recs[which].ext end - 
ext_recs[which].ext_strt); 


TESetSelect Cext_recs[which].ext_strt, 
for TE */ ext_recs[which].ext_end, TextH); 

TEDe leteCTextH); 

HLockCext_data); 

TEInsert(*ext.data, data size, TextH);/* update text */ 

HUnlockCext. data); 


/* select extent 


ext recs[whichl.ext. end = ext. recs(whichl.ext strt + 
data.size; /* update end (start unchanged) */ 


d (delta) /* only update if there was a change */ 


/* offset each following extent by change in size of 
this extent */ 
e (jzwhich*1; j<C**the_data_H).ext_cnt; ј++) 


ext_recs[j].ext_strt += delta; 
ext.recs[jl.ext.end += delta; 


) 
) 


HUnlock(the_extH); 
DisposHandle (ext_data); 
return (iac_code); 


/* clean up */ 


/** 
* Routine: ext. move 
x 


х This routine checks to see if we have left the “current 
extent”. Ifwe have, we check to see if we are the source for 
that extent. If so, the contents of that extent are written to 
the IAC driver. If we are instead mousing INTO an extent, that 
becomes the current extent. 


х/ 


8 define . SEG. . Main 

void ext.move(myEvent, w.Ptr) 
EventRecord*myEvent; 
WindowP tr и_Р4г; 


EventRecord  anEvent; 


short 1ac-code; /* result from ТАС call */ 

05Егг an-err; 

win-dateH the_data_H;  /* data associated with a window */ 
extentH the ехін; /* handle to extent block */ 
exTable ext.recs; /* for updating old extent */ 
TEHendle Техн; /* The TextEdit handle */ 

short i, the-ed, old.ext. no; 

short data_size; 

extent old_ext; /* to check for change in extents */ 
Handle ext data, t_base; 

long *] ptr; /* recast to ease setting up hdr */ 


extern Boolean ext active; 
extern Boolean chk_extent(); 
"def ine HDR_SIZE 8 


the_data_H = (win_dataH) GetWRef Con(w- Ptr); 


TextH - (**the. data. H) .wind ТЕН; 
the_extH =  (**the. data HD. the extents; 
ext.recs =  *the extH; 
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old.ext.no = curr.ext. no; 
enEvent = X *mgEvent; /* local copy for modification */ 


GlobalToLocal(&anEvent . where); 


TEClickC&anEvent where, CanEvent.modifiers & shiftKey) != Ø, 


TextH); 


if Cext_active) /* we may need to write it’s data to the IA 


driver */ | 


old.ext = curr_ext; 

the_ed = curr_ext.ed_level; 

ext_active = chk_extent(TextH, the_extH, 
(**the_data_H).ext_cnt); 


if ((old_ext.ext_strt != curr_ext.ext_strt) || 
lext active) /* we left the current extent */ 


if Ccurr_ext.src_doc==(** the_data_H).doc_ID) 
/* we were the source */ 


iac_code = ext_write(TextH, 
old.ext.ext.strt, 
(old-ext.ext end - old_ext.ext_strt), 
(**the_data_H).doc_ID, 
old. ext .hat. check, 
&the. ed); 
ext recs[old.ext.nol.ed level = the. ed; 
/* update old extent just written */ 


) 


else /* see if we've moved into one! */ 


ext active = chk extent(TextH, the. extH, 
(**the. data. H2. ext. cnt2; 
/* Since we weren't in an extent, nothing to write х/ 


) 


/** 
* Routine: ext remove 
x 


* This routine severs а link in the drivers dependency 
table. It assumes the driver will take care of removing any 
remaining data it sent. */ 


8 define . SEG... Main 
voidext.remove(w.Ptr, extP) 
WindowPtr wPtr; 


extentP extP; /* extent to remove */ 


win_dataH the_date_H; 
extentH the_ex tH; 
short iac_code; 


/* data associated with a window */ 
/* handle to extent block */ 
/* result from IAC call */ 


the_data_H = (win_dataH) GetWRefCon (и_Р4г); 
iac-code = iac_remove_dependency((**the_data_H).doc_ID, 
) (**the_data_H).the_slot, extP-»hat check); 


/** 
* Routine: poll_iac 
x 


* This routine checks with the IAC driver to see if there’ 


anything to do. It checks at 1 second intervals to avoid 
excesSive loading onsystem capacity. In order to simplify 


management of the extent ranges, extents are stored in ascend- 


ing order by starting position. This means that updating an 
extent involves adjusting the start/end of а11 SUCCEEDING 
extents by the amount the updated extent changes, but no 
preceeding extents need be touched. Storing the extents in 
random order is definitely а poor idea. */ 
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# define . SEG... Main 
void poll.iac(w Ptr) 


WindowPtr и_Р4г; 

win_dataH the_data-H;  /* data associated with a window */ 
extentH the extH; /* handle to extent block */ 
exTable ext recs; /* for walking extents to read */ 
TEHendle — TextH; /* The TextEdit handle */ 

short slot ID, vers, the. ed; /* Гог IAC */ 


long fmt. code; /* actual data format from ТАС */ 
long fmt pref(3]; /* format prefs, descending desirability */ 


long 010.54, old.end; /* TE selection before poll */ 
long  my-docID; /* so I don't read my own extents! */ 
short delta; /* change in extent size */ 

short i,j; /* traditional loop counters */ 
Handle — ext. data; /* Handle to data block */ 


short 1ас_соде = noErr; /* result from IAC call */ 
short waiting - 0; /* for IAC */ 

short doc.count = 0; /* how many ere open? */ 
extern long last. pol1; /* when we last polled IAC */ 

( (TickCount() > Clast_pol1+POLL_INT)) /* min interval */ 


/* get relevent handles, etc */ 
the-data.H = (win deteH) GetiRefCon (w-Ptr); 


slot.ID =  (**the. deta.HD. the. slot; 
іһе-ехіН = (**the. data HD. the extents; 
TextH = (**the. data. H5) . wind ТЕН; 
my-docID = C**the. data HD .doc. ID; 


iac_code = iac .statusCslot ID, &vers, &doc count, &wait- 
ing); 


г (waiting!) /* get data for each end update extents */ 
old.st = (**TextH).selStart; /* user's selection */ 
Old_end = (**TextH).selEnd; 
ехі_гесѕ = *the_extH; /* point to Ist extent */ 
^d (i20; i«C**the даба НО.ехі cnt; i++) 

if (ny docID != ext recs[il.src-doc) /*not my own! */ 


the_ed = ext. recs[il.ed level + 1; /* successor to 
lest level read */ 
1ас_соде = ext. read(w.Ptr, &the.ed, i); 
if Сіас. соде--поЕгг 2 
if (waiting -= 1) == 0) 
break; /* stop if no extents left to do */ 
) 
) 
) /* for */ 
TESetSelect Cold.st, old end, TextH); /* restore */ 


last_poll = TickCount(); /* update timer */ 
) 


/** 


х Routine: edit init 
x 


* This hendles 811 the grunt initialization. It returns NULL 
if everything went OK, non-NULL if unable to open the IAC 
driver or we aren't operating under MultiFinder. */ 


# define SEG init 
short edit. init() 
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( 


short i, К, menu limit; 
Str255  itemString; 
short result = 0; /* default optimism */ 


extern MenuHandle MyMenus[]; 
extern CursHandle ibeamHd!; 
extern long last poll; 


InitGraf C&qd. thePort?; 

InitFontsC); 

FlushEventsCeveryEvent, 2); 

InitWindows(); 

Ini tMenus(); 

TEInitO; 

InitDialogs(nil); 

InitCursor(); 

ibeamHd] = GetCursor( iBeamCursor ); 

HNoPurge( (Handle) ibeamHd] 2; /* ensure we keep it */ 


result = iac_open();/* try to get IAC driver */ 
if (result != noErr)/* couldn’t get it! */ 


NumToString CClong) result, &itemString); 
if (result==EARLY_SYS) 


ParamText C^MultiFinder^, ^^, &itemString, ^^); 
else 
РагапТехі (“the IAC дгіуег”,%” &itemString, ^^); 
) 
else /* got it! */ 


ext_active = false; 
curr.ext.hat check = 0; 


/* no “current extent? yet */ 


curr.ext.ed level = 0; 
curr_ext.ext_strt = 0; 
curr.ext.ext. end = 0; 


4 


/* handle menu init’g (don’t add link-display menu) */ 
menu limit = menuCount- 1; 
for Ci=appleMenu,k=appleID; i«menu limit; 1++,К++) 


MygMenus(i] = GetMenuCk); 


AddResMenuCMgMenus [appleMenu], CResType) 'DRVR'); 
AddResMenu(MyMenus[fontMenu], (КесТуре) “ҒОМТ”); 
for (i20; i«menu limit ;**i 2 


InsertMenu(CMyMenus i 1,2); 


/* set textstyling defaults */ 

GetFNum C*Geneva^, &the_fNum); 

the.size = 10; 

CheckItem CMyMenus[sizeMenul, 2, true); 

/* scan font menu to check default font */ 

for (1=1; i<=CountMI tems CMyMenus[fontMenu]); i++) 


GetI tem (MyMenus[fontMenu], i, &itemString); 
GetFNum C&itemString, &k); 
if (К==депеуа) 


CheckItem (MyMenus[fontMenu], i, true); 
break; 


) 


DrawMenuBar ( ); /* now user can see menu bar */ 
last_poll = TickCount(); /* so we can poll 6 1-sec 
intervals */ 
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return(result); 


/** 

ж Routine: menu_tree 

x 

* This is the standard menu-processing tree. 
х/ 


8 define . SEG. . Main 
void menu treeCmenu. sel) 
longmenu.sel; /* menu/item selected */ 


short the.menu, the item; 
GrafPtr savePort; 
char daName [256 ]; 
507255 — itemString; 
short 1; 

win-dataH the баба Н; /* data associated with а window */ 
extentP ех{Р; /* ptr to ап extent to zap on quitting */ 
TEHandle Техін; /* The TextEdit handle */ 


/* font selection */ 


extern short the_fNum, the. size; 
extern Style — the style; 

extern MenuHandle MyMenus 1; 
extern Boolean | DoneFlag; 


extern void about box C); 

extern short open.doc(), create_doc(), close_doc(), 
save_doc(); 

extern void do _clear(), do_copy(), do_cut(), do_paste(); 

extern void do_hotCopy(), do_hotPaste(), killLink_box(), 
ext_remove(); 

extern void link_display(), linkInfo_box(); 


the_item = LOWORDCmenu. se1); 
the-menu = HIWORDCmenu_sel); /* This is the resource ID */ 


if CmyWindow) 
( 


the-data.H = (win_dataH) GetWRefCon CmyWindow); 
TextH = (**the_data_H).wind_TEH; 


switch Cthe. menu) 


cese appleID: 
if Cthe item == aboutMeCommand) 


about. box; 
else 


GetItemCMyMenus[appleMenul, the item, daName); 
GetPor t(&savePort); 
(void) OpenDeskAcc(daName ); 

) SetPort(savePort); 


break; 


case fileID: 
е (the_item) 


case newCommand: 
(void) create_doc(); 
break; 


case openCommand: 
(void) open-doc(); 
break; 


case closeCommand: 
(void) close_doc(); 
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/* current attributes */ 


break; 


case saveCommand: 
(void) save_doc(); 
break; 


case quitCommand: 


DoneFlag = true; /* I want out! */ 


for (i=0; i«CE*the. data HD.ext.cnt; i++) 
( 
extP = C*C**the. data. HD. the extents) + 
(i * sizeofCextent)); 
ext_remove(myWindow, extP); 


break; 


default: 
break; 


break; /* fileID */ 


case editID: 


Switch Cthe item) 
( 


cese undoCommand: /* not implemented Cif ever!) */ 
break; 


case cutCommand: 
do_cut(); 
break; 


case copyCommand: 
do_copy(); 
break; 


case pasteCommand: 
do_paste(); 
break; 


case clearCommand: 
do_clear(); 
break; 


case hotCopyCommand: 
do_hotCopy(); 
break; 


case hotPasteCommand: 
do_hotPaste(); 
break; 


case zapLinkCommand: 
killLink_box(); 
break; 


default: 
break; 


break; /* editID */ 


case optionsID: 
a (the. item) 


case showL inksCmd: 
break; 


case showLinkInfoCmd: 
ТіпкіпҒо-БохСО; 
break; 


default: 
break; 
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breek; /* optionsID */ 


case fontID: 
for (1=1; i«-CountMItemsCMyMenus[fontMenu1); i++) 


CheckItem (МУМепиз Гоп{Мепи], i, false); 


) 

CheckItem CMyMenus[fontMenu], the item, true); 
GetItem CMyMenus(fontMenul], the item, &itemString); 
GetFNum C&itemString, &the_fNum); 

for (i20; i<8; ін)  /* set real sizes */ 


if CRealFont (the fNun, f sizes[ i12) 
SetItemStyle СМуМепиѕ [312еМепи], 1+1, outline); 
еізе 


SetItemStyle (MuMenus[sizeMenu], 1+1, normal); 


if CmyWindow) /* force a refresh */ 


SetPort CmyWindow); 
TextFont Cthe_fNum); 
(**TextH).txFont = the fNum; 
TECalText CTextH2; 

InvalRect C&myWindow-> por tRect); 


break; 


case sizelD: 


M Cthe-item<9) /% setting new size */ 


for (1=1; i«9; i++)  /* remove all checkmarks */ 


CheckItem (MyMenus[SizeMenu], i, false); 


the_size = f_sizes[the_item-1]; 
CheckI tem (MyMenus[sizeMenu], the_item, true); 


else /* setting style */ 
( (the-style & f_styles[the_item-101)/*already on?*/ 


the-style &- СТ. styles(the item-19015; /*turn off*/ 
CheckItem (MyMenus[sizeMenul, the_item, false); 


else 


the_style |= f_styles[the_item- 10]; 
CheckItem (MyMenus[sizeMenu], the item, true); 


if (myWindow)/* force a refresh */ 


SetPort CmyWindow); 
TextFace (the_style); 
TextSize Cthe.size); 
(**TextH).txFace = the. style; 
(**Тех{Н). іхбіге = (һе. 512е; 
TECalText (TextH); 

InvalRect C&nyWindow-?portRect); 


break; 


case linkDisplayID: 
link-displagCthe item - 1);/* zero-besed extent sub- 
scripts */ 
break; 


default: 


| 

| 

| break; 
) /* end switchCthe menu) */ 
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HiliteMenu(@); 


return; 


/** 
х Routine: add_disp]ay_cmdC ) 
x 


* This is the routine that is called whenever a link is 
completed. It adds a menu item to the "Links" menu so the user 
can highlightany visible links іп а distinctive fashion. */ 


8 define . SEG. Main 
void add_display_cmd(which, total) 

short which; /% position in extent array */ 
short total;  /* total 8 of extents */ 


win .dataH the data. H; /* data associated with a window */ 


extentH the_ex tH; /* handle to extent block */ 
exTable ext_recs; 
Str255 num_str, cmd_str; /* for building menu item */ 


the_data_H = (win-dataH) GetWRefCon (myWindow); 
{Ре_ех4Н = (**the_data_H). the extents; 
ext recs = *the_extH; 


( CC*X* the. data HD . ext. cnt) 
if C!link menu)  /* need to create link menu */ 


MyMenus(linkdDispMenul] = GetMenuClinkDisplayID); 
InsertMenuCMyMenus[1inkdDispMenu], 8); 
link_menu = true; 


NumToString (Clong) total, &num. str); 
( (ext_recs[which].src_doc == (**the. data. H).doc. ID) 


Strcpy(&cmd.str, “Source extent “); 
else 
strcpy(&cmd_str, “Target extent "2; 


(void) strcat(&cmd_str, &num.str2; /* build menu item */ 
AppendMenu (MyMenus[linkdDispMenul, &cmd.str); 


DrawMenuBar C); 
) 


8 define _ SEG. Main 
void link displayCext. no) 
short ех{_ло; /* which extent to highlight */ 


/* now user can see menu bar again */ 


win дабаН the_data_ H; /% data associated with a window */ 


extentH the extH; /* handle to extent block */ 
exTable ext recs; /* ptr to array of extents */ 
short old.st, old.end; /* previous selection range */ 
TEHandle TextH; /* The TextEdit handle */ 


extern voidSourceHigh(); /* assembler highlighting routine */ 


the.data.H = (win_dataH) GetWRefCon (myWindow); 


the. extH =  (**the. data. HD. the extents; 
TextH - (**the. data. H2 . wind. TEH; 
ext.recs =  *the. extH; 


old.st = (**TextH).selStart; 
old_end = (**TextH).selEnd; 


/* put а routine address into teHiHook for new highlighting 
routine */ 
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) 


(**TextH).highHook = &SourceHigh(); 
TESetSelect CClong) ext.recs[ext.nol.ext.strt, 
(long) ext_recs[ext_no].ext_end, TextH); 


while C!Button()) ; /* wait for mouse-down */ 
while (Button()) ; /* and following mouse-up */ 


/* clear teHiHook to restore normal highlighting */ 
TESetSelect CClong) old.st, (long) old_end, TextH); 
/* unhighligh extent */ 

C**TextH) .highHook = nil; 


Listing: Editor.r 


/*resource file for the test editor */ 


®include "Types.r"^ 


/* - The Menus - */ 


resource ‘MENU’ (128, “Apple”, preload) ( 


); 


128, 

textMenuProc, 

QxTFFFFFFD, /* Disable item 82 */ 
enabled, 

"id 


"About Sample..", 
noicon, nokey, nomark, plain; 


тд 


7 
noicon, покеу, nomark, plain 


resource ‘MENU’ (129, “File”, preload) ( 


); 


129, 
textMenuProc, 
бх2Е, 
enabled, 
“File”, 


“New”, | 
noicon, "N^, nomark, plain; 
“Ореп”, | 
noicon, “0”, nomark, plain; 
“Close”, 
noicon, noKey, nomark, plain; 
“Save”, 
noicon, “45% nomark, plain; 


е.м 
4 


noicon, nokey, nomark, plain; 
^Quit^, 
noicon, *Q^, nomark, plain 


resource ‘MENU’ (130, “Edit”, preload) ( 


130, textMenuProc, 
ÜxTFFFFFBD, /* Disable items #1 & #2 */ 
| “Edit”, 


“Undo”, 
noicon, “7%, nomark, plain; 


j 
9 


noicon, покеу, nomark, plain; 
“Cut’, 

noicon, “X”, nomark, plain; 
“Сору”, 

noicon, "C^, nomark, plain; 
“Paste”, 

noicon, "V^, nomark, plain; 
“Clear”, 

noicon, nokey, nomark, plain; 
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тыл 
7 


noicon, nokey, nomark, plain; 
“Hot Сору”, 

noicon, nokey, nomark, plain; 
“Hot Paste’, 

noicon, nokey, nomark, plain; 
“Remove Link”, 

noicon, nokey, nomark, plain 


); 


resource ‘MENU’ (131, "OptionsMenu^,Preload) ( 


131, /* ID */ 
textMenuProc, /* menu def proc ID */ 


0811, /* item flags */ 
enebled, /* menu enable */ 
“Options”, 


( “Show links’, 
noIcon,noKey, noMark , plain; 
“Show link info”, 

) nolcon,noKeu,noMark,plain 

); 


resource ‘MENU’ (132,*FontMenu?,Preload) ( 


132, /* ID */ 

textMenuProc, /* menu def proc ID */ 
allEnabled,  /* item flags */ 
enabled, /* menu enable */ 
“Font”, 


) 
n 


resource ‘MENU’ (133, "Sizes^,Preload) ( 
133, /* ID */ 

textMenuProc, /* menu def proc ID */ 
0811111911111111, /* item flags */ 


enabled, /* menu enable */ 
*Size", 
( “g”, 
nolcon,noKeu,noMark,plain; 
* 10”, 
nolcon,noKeu,noMark,plain; 
7427, 
noIcon,noKey, noMark , plain; 
“14°, 
noIcon,noKey, noMark, plain; 
7407; 
noIcon, noKey, noMark , plain; 
“20”, 
noIcon,noKey, noMark , plain; 
724^ 
noIcon,noKey, noMark, plain; 
“28”, 


noIcon,noKey, noMark plain; 
[му 


д 

noIcon,noKey, noMark,plain; 
“Bold”, 
noIcon, ^B^,noMark,plain; 
“Ttalic’, 
noIcon, “1%, noMark, plain; 
“Under lined”, 
noIcon, “U”,noMark, plain; 
“Outline”, 
noIcon,noKey, noMark, plain; 
“Shadow”, 

noIcon,noKey, noMark, plain 

); 


resource ‘MENU’ С 134, "Links^,Preload) ( 
134, /* ID */ 
textMenuProc, /* menu def proc ID */ 
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QxFFFFFFFF, /% item flags */ ( (185, 130, 210, 210), /% [1] */ 


enabled, /* menu enable */ Button (enabled, "0K!^), 
“Links”, (10, 20, 26, 320), /* [2] */ 
( SteticText (disabled, “Information About Current Registered 
) Links"), 
); (35, 300, 170, 316), /* [3] */ 
UserItem (enabled), 
/* — The Windows - */ (35, 20, 170, 300), /* [4] */ 
UserItem (disabled) 
resource ‘WIND’ (128, ^a Window”) ( 

(64, 60, 314, 460), ); 

documentProc, 

visible, /* Scroll bar for link-info dlog */ 

noGoAway, resource 'CNTL^ (129,Purgeable) ( 

0х0, (35,300, 170,316), 

“Untitled? 0, /* value */ 

); visible, 
0, /* mex */ 
/* - The Alerts/Dialogs (with 011$) - */ 0, /* min */ 
scrollBarProc, /* type */ 
/* 128 is the about box */ 0, /* refcon */ 
/* 129 is the link info box */ "х” 
/* 256 is “No IAC” error box */ 
/* 257 is the IAC error alert */ 
/* 258 is the "Not in any extents^ alert */ resource 'ALRT^ (256,Purgeable) ( 
/% 259 is the “Sure you want to kill this extent?" Alert */ (100, 100, 220, 400), 
/% 260 is the “Save changes?” alert */ 256, 
( OK, visible, soundi,/* [1] */ 
resource 'DLOG^ (128,Purgeable) ( ОК, visible, sound!,/* [2] */ 

(61, 80, 301, 420), OK, visible, sound1,/* [3] */ 

altDBoxProc, OK, visible, soundi /* (4) */ 

visible, 

noGoAway, I 

0x0, 

128, resource ‘DITL’ (256,Purgeable) ( 

“x° ( (00, 200, 110, 280),/* [1] */ 

); Button (enabled, “Rats!” ), 
(20, 72, 84, 280), /* (2] */ 
resource 'DITL^ C128,Purgeeble) ( StaticText (disabled, 

( "Unfortunately, we cannot find “0. “ 
(200, 110, 225, 230), /* (11 */ “Without it, there is no point in going on. Fare- 
Button (enabled, “Wonderful!”}, well...*); 

(15, 65, 31, 215), /* [2] */ (94,20, 110, 150), /* [3] */ 
StaticText (disabled,"The Great IAC Sample Program!^), StaticText (disabled, *IDz^2") 
(40, 20, 56, 320), /* ІЗІ */ ) 

StaticText (disebled,"This copy: ^9"), ); 


(60, 20, 124, 320), /* (41 */ 
StaticText (disebled,"This sample is designed to show off resource 'ALRT^ (257,Purgeable) ( 


the * (100, 100, 240, 400), 
*ver- ious capabilities of the SAWS Inter- Application 257, 
ы ( OK, visible, $0ипд1, /* [1] */ 
“Communications Driver. It may be used freely. Send ОК, visible, soundi,/* [2] */ 
questions, etc" ОК, visible, soundi,/* [3] */ 
е. to: *), OK, visible, sound! /% [4] */ 
(124, 119, 140, 219), /* [5] */ ) 
StaticText (disabled, “Frank Alviani"), ); 
(140, 120, 188, 220), /% [6] */ 
StaticText (disebled,"P.0. Box 8744 Waukegan 111 60079") resource 'DITL^ (257,Purgeable) ( 
( (105, 110, 139, 190),  /* (1) */ 
); Button (enabled, "Rats! ^), 
(10, 67, 90, 280), /% (2) */ 
StaticText (disebled,^IAC Error “0 was encountered during 
resource 'DLOG^ С 129, *1іпк info”,Purgeable) ( the * 
(80, 86, 300, 426), **] operation, which was not completed. Sorry!) 
81tDBoxProc, ) 
visible, ); 
noGoAway, 
0х0, resource “МЕТ” (258,Purgeable) ( 
120, (100, 100, 200, 400), 
e» 258, 
}; ( ОК, visible, sound!,/* [1] */ 
ОК, visible, sound1,/* [2] */ 
resource 'DITL^ C129,Purgeeble) ( ОК, visible, soundi,/* [3] */ 
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ок, 
); 


resource 


( (70, 


visible, soundi  /* [4] */ 


‘DITL’ (258,Purgeable) ( 
110, 95, 190), /* [1] */ 


Button (enabled, ^Rats! ^), 


(10, 
StaticText (disabled,"Sorry! You are not in any extent." 


62, 58, 290), /* [2] */ 


“Therefore no link can be severed."^) 


); 


resource 
(100, 
259, 

( ок, 
OK, 

OK, 

OK, 


); 


'ALRT^ (259,Purgeable) ( 
100, 200, 400), 


visible, soundl,/* [1] */ 
visible, sound1,/* [2] */ 
visible, soundi,/* [3] */ 
visible, soundi  /* [4] */ 


resource 'DITL^ (259,Purgeable) ( 


( (65, 


110, 90, 190),  /* [1] */ 


Button (enabled, ^Rats!^), 


(10, 


62, 42, 290), — /* [2] */ 


StaticText (disabled,"Are you SURE you want to remove 


this " 


“link? This cannot be undone."^) 


); 


resource ‘ALRT’ (260, Purgeable) ( 


(100, 


100, 250, 400), 


visible, sound!,/* [1] */ 
visible, soundi,/* [2] */ 
visible, soundi,/* [3] */ 
visible, soundi  /* [4] */ 


resource 'DITL^ (260, Purgeable) ( 


( (80, 


15, 105, 05), — /* [1] */ 


Button (enabled, Save"), 


(115, 15, 


140, 95}, /* [2] */ 


Button (enabled, “Сәпсе1”), 


(116, 205, 141, 285) 

Button (enabled, "No*), 
(15 
StaticText (disabled, “Do you want to save the changes made 


to 02”) 
) 
); 


/* [3] */ 


75, 63, 285), /х(41%/ 


resource ‘ALRT’ (261,Purgeable) ( 


(100, 


100, 200, 400), 


visible, soundl,/* [1] */ 
visible, sound!,/* (21 */ 
visible, sound!,/* [3] */ 
visible, sound! /* [4] */ 


resource ‘DITL’ (261,Purgeable) ( 


( (70, 


110, 95, 1900),  /* [1] */ 


Button (enabled, "0K^), 


(10, 


62, 58, 290), /* (2] */ 


StaticText (disabled,"Doc.ID = 70 hatCheck = ^1") 


O The Definitive MacTutor, Vol. 4 


/* - Miscellaneous Resources - */ 


); 


resource ‘SIZE’ (-1) ( 
dontSaveScreen, 
acceptSuspendResumeEvents, 
disableOptionSwitch, 
canBackground, 
multiF inderAware, 
98304, 
98304 


/* preferrred size = 128K - 32k */ 
/* min size = 128K - 32k */ 


type ‘IAC!’ as ‘STR ‘; 


resource ‘IAC1’ (Ø) ( 


“Sample IAC Application - Version 1.981” 


) 


resource ‘ICN®’ (128, Purgeable) ( 


( /* array: 2 


) 
); 


/* [1] 
$"0001 
$"00 10 
$0101 
$^113C 
%”4248 
%%0412 
$^0040 
$^0004 
/* (21 
$^"0001 
$"001F 
$"01FF 
$^1FFF 


*/ 

0400 0002 
1140 0022 
C104 02А4 
8010 2249 
8041 2093 
В007 0221 
ІҒЕТ 0020 
1040 0002 
х/ 

0400 0003 
FFCO 003Ғ 
FFFC ОЗЕР 
FFFF 3FFF 


8А00 
08А0 
9082 
0008 
3022 
8007 
021Ғ 
2880 


8Е00 
ЕҒЕй 
FFFE 
FFFF 


%”ТҒЕҒ FFFF 3FFF FFFF 
$“O7FF FFFF @3FF FFFF QIFF FFFF 
$"007F FFFF 003Е FFFF 00ІҒ FFF7 
$0007 FFCO 0003 EF80 0001 C700 


elements */ 


0004 5109 
0044 ВҒ00 
054С 2041 
44А0 3Ғ04 
1123 (814 
0100 А007 
0010 0417 
0001 4500 


0007 0Ғ00 
007Ғ FFFÜ 
O7FF FFFF 
TFFF FFFF 
IFFF FFFF 


resource ‘ICN’ (129, purgeable) ( 
( /* array: 2 elements */ 


) 
E 


/* [1] 
$"0FFF 
$"08F8 
$°08 IF 
$08 IF 
%”08ҒҒ 
%”080Ғ 
$"08FC 
$^"0807 
/* (21 
$"0FFF 
$"0FFF 
$"0FFF 
$°OFFF 
$"0FFF 
$“OFFF 
$"0FFF 
$"0FFF 


*/ 


ҒС00 0800 0600 0800 05С0 


0450 0800 
ЕЙІҒ 0800 
0011 0800 
Е011 0800 
С011 0800 
0019 0800 
FE11 0800 
х/ 

FCOO OFFF 
FFFO OFFF 
FFFF OFFF 
FFFF OFFF 
FFFF OFFF 
FFFF OFFF 
FFFF OFFF 
FFFF OFFF 


0428 
0011 
0011 
0011 
0010 
0011 
0011 


FEQQ 
FFF8 
FFFF 
FFFF 
FFFF 
FFFF 
FFFF 
FFFF 


resource ‘BNDL’ (128) ( 
‘IACI’, 


0, 


‘1С№ 7, 
( 


0, 128, 
1, 129 


), 
‘FREF’, 


08ІҒ ETF4 
0803 ҒС11 
08ІҒ FE11 
083С 0019 
080Ғ Ғ811 
083Ғ Е011 
0800 0011 


OFFF FFCO 
OFFF FFFC 
OFFF FFFF 
OFFF FFFF 
OFFF FFFF 
OFFF FFFF 
OFFF FFFF 
OFFF FFFF 


0008 2080" 
0089 C288" 
080Е 4020" 
8124 4082" 
084Е ТЕВЕ” 
0080 6007" 
0008 0820" 


0000 8200", 


000Ғ ҒЕ80" 
QOFF FFF8" 
OFFF FFFF^ 
FFFF FFFF^ 
OFFF FFFF^ 
DOFF ҒЕҒЕ” 
000F FFEQ" 
0000 8200" 


0800 04A0" 
0800 0012" 
0800 0010” 
0800 0010” 
0800 0011" 
0800 0011" 
0800 0010” 


ВЕРЕ FFF1", 


OFFF FFE" 
ФЕЕЕ FFFE^ 
OFFF FFFF^ 
OFFF FFFF^ 
OFFF FFFF^ 
OFFF FFFF^ 
OFFF FFFF^ 
OFFF FFFF^ 
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resource ‘FREF’ (128, purgeable) ( 
APPL’, 
0, 


wa 


); 


resource ‘FREF’ (129, purgeable) ( 
‘TEXT’, 


д 
e^ 


); 


include $$ShellC^hixEtc^) "editor.code^; 
code segments in! */ 


Listing: 


[***X 
x 
*These are the routine required to handle the major dialog 


*boxes. 
44% / 


/* make sure we get 


Boxes .c 


include <types.h? 
include  «memory.h? 
include <quickdraw.h> 
include <toolutils.h 
include <windows.h> 
include <controls.h) 
include <dialogs.h> 
include <textedit.h» 
include <string.h> 
include <resources.h) 
include «fonts.h» 
include <menus.h) 
include <Events.h)> 


include «iac.» 
define PUBLIC extern 


8 include <Editor.h) 
[** 
* Routine: about_box 
x 


ж This handles the about box; the current name of this app 
is displayed to make working with multiple copies easier. No 
other fancy effects this time... */ 


8 define . SEC... Main 
void about_box( ) 


( 
DialogPtr d.Ptr; 
short item. hit; 
Ptr сигАрМаР; /* LOW MEMORY GLOBAL! */ 
curApNmP = (Ptr) 0х910; 
PARAMTEXT CcurApNnP,, *^,"", ^"); /* Pascal interface ver. */ 
d Ptr = GetNewDialog CABOUT.DLOG, nil, CWindowPtr) -1); 
ModalDialog (nil, &itemhit); 
DisposDialog (d_Ptr); 


/** 
х Routine: linkInfo_box() 
x 


* This routine displays а dialog box with information about 
each link in the current document. */ 
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* define SCROLL_BAR_ITEM 3 
8 define LIST.BOX 4 


8 define . SEC. . Main 
void linkInfo.boxC(O 


( 

short iac. code; /* result from IAC call */ 
DialogPtr а Ptr; 

short i, lines.vis;  /* scratch */ 

win_dataH the. data. H; /* data associated with a window */ 
extentH the extH; /* handle to extent block */ 
exTable ext.recs; /* ptr to extent-array */ 

TEHendle — TextH; /* The TextEdit handle */ 
ControlHandle зсго11Н; /* Scroll bar handle */ 

String( 16) ext_no; /* holds converted values */ 

short i-type; /* for GetDItem */ 

Handle і лагі; 

Rect і_рох; 

сһаг *nsg; 

short e cnt; /* count of active extents */ 
info.tbl census_info; /% census info for every extent */ 


Point mouse. loc; 
Boolean b; 


short item hit = 0; 


/* get necessary handles, etc. set up */ 
the.data.H = (win_dataH) GetWRefCon (myWindow); 
the_extH = (**the_data_H). the extents; 


iec.code = iac census(&e.cnt, &census_info); /* que раза, 
driver? */ 
г (e_cnt==0) 


return; 


/* set up text area */ 

d-Ptr = GetNewDialog CABOUT.LINKS, nil, (WindowPtr) -1); 
SetPort ((GrafPtr) d_Ptr); 

TextFont (monaco); /* mono-spaced for easu lauout */ 
TextSize (9); 

GetDItem (d_Ptr, LIST BOX, &i_type, &i.hdnl, &i_box); 

/* text-area box */ 
i-box.right += 1; 
FremeRect (&i_box); 
InsetRect (&i_box, 2, 2); 
Тех{Н = TENew (&i_box, &i_box); 
lines.vis = Ci.box.bottom - i_box.top) / 12; /* text lines 

visible */ 


/* overlap scroll bar properly */ 


/* margin for drewing */ 


/* Highlight button */ 

GetDItem Са Ріг, ok, &i-type, &i.hdnl, &i-box);/* button */ 
InsetRect (&i.box, -4, -4); 

PenSize (3, 3); | 

FremeRoundRect (&i_box, 16, 16); 

PenNormal(); 


/* set up scroll bar */ 

scrollH = GetNewControl CABOUT.LINKS, d_Ptr); 

if Ce_cnt > lines_vis)/* enable control */ 
SetCtlMax (scrollH, e_cnt); 

/* put in header */ 

msg = “Ext® -Doc.ID- Hat check Edition\n\n”; 

TEInsert (msg, (long) strlen(msg), TextH); 


/* do each extent in turn */ 
for (i20; i<e_cnt; 1++) 
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өргіп Фехі no, “440”, i); 
TEInsert (&ext no, 4L, ТехіН); 
sprintf(&ext. no, “ $%8X”, census_info.ext_entryli].doc_ID); 
TEInsert (Фехі no, 101, TextH); 
sprintf(&ext.no, “490”, 
census. info.ext.entry[il.hat check); 
TEInsert (&ext.no, 9L, TextH); 
sprintf(&ext.no, "Z9d",census-info.ext entryliJ.ed. level); 
TEInsert (&ext no, 9L, TextH); 
TEKey(Ox0D, Техн); /% An to end line */ 


TextFont(systemFont); 


/* so static text looks right */ 
TextSize (12); 


/* 
*The normal modal dialog loop. You can’t do anything except 
look at the range of each extent. */ 
while Citem hit != ok) 


ModalDialog (nil, &item hit); 
cn Citem hit) 


case SCROLL BAR..ITEM: 
GetMouse (&mouse_loc); 
GlobalToLocal (&mouse. loc); 
/* scrolling code here later */ 
break; 


default: 
break; 
) 
) 
DisposeControl Cscro11H2; 
DisposDialog (d.Ptr); 
SetPort(FrontWindow()); 


/* clean up after ourselves */ 


) 


жж 
* Routine: killLink box 
x 


Ж This 13 the user interface that allows а user to "cut^ а 
hot link. */ 


8 define . SEC. Main 
ыы. 


short item hit; 
extern voidkill_extent(); 
if Cext active) 


item.hit = StopAlert (КІШ. ЕХТ, nil); /* Are you SURE? */ 
if Citem hit == ok) 


kill_extentd); 
) 


else 


item hit = StopAlert CNOT_IN_EXT, nil); /* not in any 
extent */ 


) 
Listing: 


ххх 

x 

*These are the routines required to actually carry out the 
document-handling functions. They are invoked from menu .tree() 
and are arranged in alphabetic order to simplify finding them. 
Each ensures that the menus are properlyenabled and disabled. 
ху 


Doc-rtns.c 
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include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 
include 


<types.h? 
‹тетогу.һ› 
«packages .h? 
<quickdraw.h> 
«toolutils.h» 
<windows .ћ› 
«dialogs .h> 
«menus .h? 
«textedit.h? 
<string.h> 
«Гі1ев.һ» 
«resources.h? 


f$ + + + 3$ 3$ + 3$ 3: 3f 3 2%: 


include «iac.» 
define PUBLIC extern 
include «Editor.h? 


"def ine noErr Ü 
"igef ine fnfErr 


/* 0 for success */ 
-43 /* File not found */ 


/** 


x Routine: close. doc 
x 


* This is the code required to close (and save if necessary) 
а document. */ 


8 define . SEC... Main 
rius close. docC) 


win_dataH the. data. H; /* data associated with а window */ 
extentH the_ex tH; /* handle to extent block */ 
exTable ext_recs; /* ptr to array of extents */ 
TEHandle  Тех4Н; /* The TextEdit handle */ 

short i, item, nm_len; 

short jac_code; /* result from IAC call */ 


Str255 støð; 


extern short save_doc(); /% saved updated document */ 


extern WindowPtr myWindow; /* the text window */ 
8 define no3 /* button id */ 


the-data-H = Cwin_dataH) GetWRefCon (myWindow); 


the_extH =  (**the. data. HD. the extents; 
TextH - (**the. data. H5) .wind ТЕН; 
ext.recs = *the_extH; 


/* check about saving, etc. */ 
и (C**the. data H5 .dirty) 


пт. Леп = C**the. data. H5).doc f ile.nm. length; 
if (nm len) 


РагапТехі (&C**the. data.Ho.doc file nm, "*, "^, “*); 
else 
ParamText (*Untitled^", "^, 4” 4%); 
item = StopAlert (SAVE CHANGES, nil); 
switch Citem) 
( 
case ok: 
save. doc(); 
break; 
case cancel: 


return 0; 
break; 


/* don^t delete extents, etc. */ 


case no: 


219 


break; 


) 


/* shut down extents... */ 
for (i20; i«(**the. data. HD.ext. cnt; 1++) 


1ас_соде = iac remove dependencyCext.recs[i].src. doc, 
C**the. data. HD. the. slot, 
ext recs[ il.hat. check); 


if (1ас_соде != noErr && iac_code != NO. SUCH. DEP) 
( 


NumToString ((long)iac_code, &st0); 
ParamText (&st2, "Remove Dependency^,nil,ni1); 
item = StopAlert CIAC_ERR_ALRT, nil); 


) 


/* clean up storage associated with window */ 
the-data.H = (win_dataH) GetWRef ConCmyWindow); 
DisposHandleCCHandle) (**the. data. H2. the extents); 
DisposHandle( (Handle) the. data. H); 

CloseWindow (myWindow); 


/* put menu items into proper states */ 

EnableItem CMyMenus(f ileMenuJ, newCommand); 

EnableItem (MuMenus[f ileMenul, openCommand); 

DisableItem CMyMenus[f ileMenu], closeCommand); 

DisableItem CMyMenus(f ileMenu], saveCommand); 

DisableItem (MyMenusleditMenu], Ø); — /* nothing to edit */ 
DisableItem (MyMenus[optionsMenul, 0); 

DisableItem CMyMenus[fontMenu], 2); 

DisableItem CMyMenus[sizeMenu], 0); 


DeleteMenu (1inkdDispMenu); /* no doc, по menu.. */ 
DisposeMenu СМуМепиѕ [1 inkdDispMenu]); 
MyMenus[]inkdDispMenu] = nil; 


DrawMenuBar ; 


) 


/** 


* Routine: create. doc 
x 


* This is the code for creating а new document. */ 


* define . SEC. . Main 
short create. doc() 


win_dataH the_data.H; /* data associated with a window */ 
extern WindowPtr myWindow; 


extern void setup_wind(); 


/* the text window */ 
/* set up window */ 
setup_wind(); /* create window & data structures 
ы 

the_data_H = (win-dataH? GetWRefCon CmyWindow); 

(**the. data. H2.doc f ile. nm. length = 0;/* no name yet */ 


/* put menu items into proper states */ 

DisableItem СМуМепиѕ С? ileMenuJ, newCommand); 

DisableItem (MyMenus[f ileMenu], openCommand); 

EnableItem C(MyMenus[f ileMenu], closeCommand); 

EnableItem C(MyMenus[f ileMenul, saveCommand); 

EnableItem CMyMenusleditMenu], 0); /* stuff to edit */ 
EnableItem CMyMenus[optionsMenul, 0); 

EnableItem C(MyMenus[fontMenul, 02; 

EnableItem (MyMenus[sizeMenu], 0); 

DrawMenuBar ; 


) 


/** 
* Routine: open_doc 
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x 


* This is the code required to open a document. After 
opening the doc, reading in the text, and reloading the 
extents, it checks to see if ther are any documents open of 
which it was a target in a previous life, and re-establishes 
those links. After that, it re-starts any links for which it 
was the source. */ 


8 define —SEG— Main 
= open.docC) 


ІОРагат the. blk; 

Handle txtH; /* Handle to text itself */ 
Handle extRH; /* extent-resource handle */ 
long int  txt.size; /* for TextEdit */ 

SFReply asreply; /* for SFGetFile */ 

Point where; 

SFTypeList the_types; 

05Егг an_err ; 

short res refNum; /* for resource work */ 

short Slot ID, vers, the. ed; /* for IAC */ 

short c-ndx, e.ndx, e.cnt;/* census-walking loops */ 
long t.doc;  /* temporaries to avoid memory problems */ 
short t.slot, t hatchk; 

exTable ext.recs; /* ptr to extent-array */ 


win_dataH (һе data. H; 
win_dataH  winRH; 


/* data associated with & window */ 
/* window data from saved file */ 


TEHendle Текхін; /* The TextEdit handle */ 

info_tb] X the.census; /* info for each dependency */ 
short 1ас_соде = noErr; /* result from IAC call */ 
short doc_count = 0; /* how many аге open? */ 
short ext.so fer = 0;  /* counter for ‘Links’ menu */ 


extern void setup-wind();  /* set up window */ 
extern void add_display_cmd(); /* update ‘Links’ menu */ 


SetPt (&where, 80, 100); 

the_tupes[0] = (05Туре) 0х54455804:  /* ‘TEXT’ */ 

SFGetFile C&where, *^, nil, 1, &the types(2], nil, 
&a_reply.good); 

( Са. reply.good) 


/* әп егг = SetVol(nil, &a_reply.vRefNum); /* set default 
volume */ 
ап_егг = FSOPEN (&a.reply.fName, a.reply.vRefNum, &fRef); 


the-blk.ioCompletion = nil; 

the. blk.ioRefNum = fRef; 

ап_егг = PBGetEOFC&the blk.qLink, false); 
txt_size = (long int) the. blk.ioMisc; 
txtH = NewHandle (txt. size); 


HLockCtxtH2; 
the-blk.ioCompletion = nil; 
parameter block */ 


/* set up driver 


the_blk.ioRefNum = fRef ; 
the_blk.ioBuffer = *ixtH; 
the-blk.ioReqCount = txt size; 
the-blk.ioPosMode = fsFromStart; 


the-blk.ioPosOffset = 9; 
an_err = PBRead(&the blk.qLink, false); 


setup_wind(); /% set up window and TE record */ 
SETWTITLE CmyWindow, &areply.fName); /*window title OK*/ 
the_data_H = (win_dataH) GetWRefCon CmyWindow); 

TextH = (**the_data_H).wind_TEH; 
TESetText (*txtH, txt_size, TextH); 
HUnlock(txtH); 
DisposHandle (txtH); 


/* TE record */ 
/* no longer needed */ 


/* get saved data & attach it to the window */ 
res.refNum = OPENRESF ILEC&a. reply.fName?; 
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extRH = GetResource (‘EXIN’, Ø); /* get extents */ 
DetachResource CextRH2; /* remove from resource manager */ 
DisposHandleCCHandle) (**the_data_H). the. extents); 

/* kill old table */ 
(**the. data. Н). the extents = extRH; 


winRH = Cwin_dataH) GetResourceC'EXTN'/, 1); /* get saved 
window data */ 

(**the_data_H).doc-ID = (**winRH2.doc. ID; 

(**the_dataH).ext_cnt = C**winRHD. ext. cnt; 

DisposHandle( (Handle) winRH);/* no longer needed */ 


the blk.ioCompletion = nil; 
the_blk.ioRefNum = fRef ; 
an_err = PBClose(&the blk.qLink, false);/* close file */ 


/*We get a census of existing dependencies, and check them 
against our extent data. For each match, we make that the 
“available dependency’ and re-establish the link. */ 


іас-соде = iac_census(&doc_count, &the_census); 
if Сіас-соде == noErr) 


e_cnt = (**the_data_H).ext_cnt; 
HLockCextRH); /* IAC calls may move memory */ 


for (c_ndx=0; c_ndx<doc_count; c_ndx++)/* walk census */ 


ext recs = *CextentH) extRH; /* base of table */ 
for Ce_ndx=8; e_ndx<e_cnt; е_пдх++)/* walk extents */ 


if CCthe. census .ext entry[c. ndx1.doc. ID == 
ext. recs[e.ndxl.src.doc) && 
(the_census.ext_entry[c_ndx].hat check == 
ext. recs[e. ndx].hat. check)) 


/* make this dependency “available” for completion */ 
jac_code = iac. available dependencyC 
ext.recs[e-ndx]1.src. doc, ext. recs[e. ndx].hat check); 


/* complete “available dependency” */ 
t_doc = 0; /* temps across ТАС calls */ 
t.hatchk = 0;  /* already made extent avail */ 
t-slot = (**the data. HD. the. slot; 
1ас_соде = iac.complete dependency(&t. doc, 
&t.slot, &t_hatchk); 
C**the. data. H2). the. slot = t_slot;/* could change */ 


/* read initial copy of data from restarted link */ 
the. ed = 0; 
їас_соде = ext read(myWindow, &the ed, e_ndx); 


ext so .far += 1; 
add. display.cmdCe.ndx, ext so. far); 
/* add link to menu */ 


) 
) /* for */ 
) /* got census */ 


if (е cnt) /* restart links for which we are source */ 


ext.recs = *(extentH) extRH; 

t_doc = C**the. data. H2 .doc ID; 
t_slot = C**the. data. HD. the. slot; 
for Се. лах-0; е пдх<е cnt; e.ndx**) 


if (ext_recs[e_ndx].src_doc == 
ЭМ ыр 


t_hatchk = ext.recs[e. лдх1.һа( check; 
the_ed = 0; 
iac_code = iac_add_dependencu(kt_doc, 
&t_slot, &t_hatchk, &the_ed); 
(*¥*the_data_H). the. slot = t_slot;/* could change */ 
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/* write data to restarted dependency */ 
iac.code = ext_write(TextH, 
ext_recs[e_ndx].ext_strt, 


/* ext_recsl[e_ndx].ext_strt - 
ext. recs[e ndxl.ext end, */ 

1, /* temporary splint */ 

t. doc, 

t hatchk, 

&the. ed); 


ext recsle. ndx].ed level = the. ed; 
ext.so far += 1; 
add. display.cmdCe. ndx, ext. so. far); 
/* add link to menu */ 
) 
) 


HUnlockCextRH); /* unclutter memory */ 


/* put menu items into proper states */ 

DisableItem CMyMenus[f i leMenu], newCommand); 

DisableItem (MyMenus[f ileMenul, openCommand); 

EnableItem (MyMenus[f ileMenuJ, closeCommand); 
DisableItem (MyMenus[fileMenu], saveCommand); 

EnableItem (MyMenusleditMenu], 0); /* stuff to edit */ 
EnableItem (MyMenusloptionsMenu], 0); 

EnableItem (MyMenus[fontMenul], 0); 

EnableItem C(MyMenus[sizeMenul, 0); 

DrawMenuBar ; 


) 
) 


/** 
x Routine: save. docC) 
x 


* This is the code required to save а document. 
x 


® define . SEC... Main 
short save_doc() 


( 

win_dataH the_data_H; /* data associated with a window */ 
TEHandle Техн; /* The TextEdit handle */ 
ІОРагат the. blk; 

Handle txtH; /* Handle to text itself */ 
Handle іпр.Н; /* temporary for resource work */ 
short nn. len; 

short refNum, res refNum; 

Str255 prompt, or ig_Name; 

SFReply aReply; 

Point where; 

05Егг anErr; 

long int txt. size; 


the_data_H = (win.dataH) GetWRefCon (myWindow); 
TextH - (**the. data. H2 .wind. ТЕН; 
пт_]еп = (**the. data. HD.doc. f ile nm. length; 


if (nm Теп--0) /* invoke SFPutFile for file name */ 


where.h - 80: 

where.v = 80: 

SFPutFile C&where, “Name your new document”, “IAC Doc", 
nil, &aReply); 

и (аКер1у. 9004) 


strcpy(&(**the_data_H).doc_file_nm, &aReply.fName); 
/* CHECK! */ 
) 


else 
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return 0; 


) 


enErr = FSOPENC&(**the_data_H).doc_filenm, aReply.vRefNum, 
&ref Num); 
if (anErr) /* mau not exist yet.. */ 


if CanErr==fnfErr) 


anErr = CREATEC&(**the_data_H).doc_f ile_nm, 
aReply.vRefNum, 'IAC1^ , "ТЕХТ’); 

anErr = FSOPENC&(**the_data_H).doc_f ile. nm, 
aReply.vRefNum, &refNum); 

(void) CREATERESF ILEC&C** the. data H) . doc. f ile. nm); 


else 


return CanErr); 


res_refNum = OPENRESFILEC&C** the. data. Н). doc. f ile-nm); 


/* save text itself in data fork */ 
txtH = C**TextHD.hText; 

txt_size = GetHandleSize (txtH); 
HLock( tx tH); 

the-blk.ioCompletion =nil; 
the_blk.ioRefNum = refNum; 
the-blk.ioBuffer = *txtH; 
the-blk.ioReqCount =txt_size; 

the. blk.ioPosMode = fsFromStart; 
the-blk.ioPosOffset = 0; 

anErr = PBWriteC&the blk.qLink, false); 
HUnlockCtxtH2; 


/* save extents in 'EXTN/ resource */ 
( (CountResources ('ЕХТМ’)) /* updating existing copy */ 


tmp.H = GetResource C'EXTN^, 0); /* read old version */ 
RmveResource (tmp_H); /* kill it */ 
tmp-H = GetResource C'EXTN^, 1); /* read old version */ 
RmveResource (tmp. H2; /* kill it */ 


) 

AddResource ((**the. data Н). the extents, 'EXTN^, 0, nil); 
AddResource ((Напд]е) the data. H, "ЕХТМ”, 1, nil); 
UpdateResF ile Cres. refNum); 


/* close up shop till next time */ 
the-blk.ioCompletion =п11; 
the-blk.ioRefNum = refNum; 

enErr = PBClose(&the_blk.qlink, false); /% close file */ 
the-blk.ioCompletion =п11; 

the_blk.ioNamePtr = nil; 

the-blk.ioVRefNum = aReply.vRefNum; 

anErr = PBFlushVol C&the blk.qLink, false); 

/* ensure disk updated */ 


SETWTITLE CmyWindow, &aReply.fName); 


(**the_data_H).dirty = false; 
return (0); 


) 


хх 


* Routine: setup_wind 
x 


* This allocates the window and creates the TextEdit data 
structure andauxiliary data record required. */ 


# define . SEG. Main 
void setup. windC) 
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( 

Rect txRect; 
extentH temp_extH; 
Str255 tStr; 


/* handle to extents block */ 


extern WindowPtr myWindow; 
extern WindowRecord wRecord; 
extern short the_fNum, the size; /* text attributes */ 
extern Style the. style; 


/* the text window */ 


myWindow = GetNewWindow(windowID, &wRecord, CWindowPtr) -1); 

Se tPor t(myW indow); 

txRect = myWindow->portRect; 

InsetRect(&txRect, 4, 0); 

TextH = TENew(&txRect, &txRect); /* Not growable, so 
destRect == viewRect */ 

сигг-ехі ло = -1; /* no ‘current extent’ yet */ 


the_data_H = Cwin_dataH) NewHandleCsizeof Cwin_data)); 
/* space for data */ 

SetWRefCon CmyWindow, (long int) the_data H); 

/* keep with window */ 

(**the_data_H).the_slot = 0; /* slot_ID for this document */ 

(**the. data.H).doc.ID = 0; /* document ID for this doc */ 

(**the. data. H).ext. cnt = 0; /* No. of extents with this doc 
*/ 

(**the_data_H).wind_TEH = TextH; /* TE handle for this 
window */ 

(**the_data_H).dirty = false; 

(**the_data_H).relevent = 0; 


/* empty block of extent records */ 

temp_extH = CextentH) NewHandle(sizeofCextent)); 
C**temp_extH) һә check = 0; 
(**temp_extH).ed_level қ 
(**temp_extH).ext_strt 

range */ 

(**temp_extH).ext_—end = 0; 
(**{Не_да{а_Н). the extents = 


0;  /* start & end of extent 


temp. extH; 


(**TextH).txFont = the fNum; /% set text attributes */ 
(**TextH).txSize = the.size; 
(**TextH).txFace = the. style; 


) 
Listing: Edit.IAC.rtins.c 


include <types.h) 
include «memory.h? 
include <quickdraw.h> 
include «toolutils.h? 
include <windows.h> 
include <dialogs.h> 
include <menus.h> 
include “textedit.h> 
include <string.h> 
include «files.» 
include <resources.h>: 


1$ tt - 1$ 3f 3$ 2 2 + 3$ se 


* include <iac.h> 
8 define PUBLIC extern 
8 include <Editor.h 


"define поЕгг 0 /% 0 for success */ 


хх 


*Routine: Set Current Extent 
x 


ж This is а local routine to set the fields in the 'current 
extent’ structure in the window data record. It is called by 
both hotCopy and hotPaste routines, since by definitions the 
extents they def ine become the “current extent’. */ 


я define . SEC... Main 
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void set_curr_ext(the_data_H, which) 
win_dataH the_data_H; /* data associated with the window */ 


short which; /* 8 of extent which is now current */ 
extentH the_ex tH; /* handle to extent block */ 
exTable ext recs; 

the_extH = (**the. data. HD. the extents; 


ext recs = Хіһе extH; 


curr_ext.src_doc = ext recs[which]l.src. doc; 
curr-ext.hat.check = ext .recs[which].hat. check; 
curr.ext.ed level = ext.recs[which]l.ed level; 
curr_ext.ext_strt = ext recs[which].ext strt; 
curr_ext.ext end = ext recs(which].ext end; 


) 


[** 
*Routine: do_hotCopy 

x 

* This routine is responsible for creating а new dependency 
source and notifying the IAC driver. It is called primarily by 
the “source” program. %/ 


* define _SEG__ Main 


void do_hotCopyC ) 

( 

win_dataH  the.data.H; /Х data associated with a window */ 
TEHandle TextH; /* The TextEdit handle */ 

extentH the_ex tH; /* handle to extent block */ 
exTable ext_recs; 


long the_doc; /* local copies due to memory mashing */ 


short — slot ID, h.check, the. ed; 

short e_cnt; 

short item_hit; /* error processing */ 
Str255  err.str, str2; 

short іас-егг = noErr; 

Boolean in_extent = false; 


extern Boolean chk_extent();  /* sets “current extent” if 
found */ 
extern void add display. cmd(C); 


extern void set curr ext); 


/* update ‘Links’ menu */ 
/* update global structure */ 


extern Boolean ext.active; 


the.data. H = (win_dataH) GetWRefCon CmyWindow); 


the_extH = (**the_data_H). the extents; 
TextH = (**the_data_H).wind_TEH; 
the.doc = (**the_data_H).doc_ID; 
Slot_ID =  C**the. deta HD. the. slot; 
e_cnt = (**the. data. H).ext. cnt; 
h.check = 0; 


г Clchk extentCTextH, the_extH, (**the_data_H).ext_cnt)) 


iac_err = iac.add dependency(&the. doc, &slot ID, &h. check, 
&the. ed); 
if (іас-егг == noErr) 


SetHandleSize (CHandle)the_extH, sizeof (extent) * 
Ce-cnt* 122; 

ext.recs = Хіһе extH; 

ext recs[e.cnt].hat check = h_check; 

ext.recs[e.cnt].ed level = the. ed; 

ext_recsfe_cnt].ext_strt = (**TextH).selStart; 

ext.recsfe.cnt].ext end = (**TextH).selEnd; 

ext .recs[e-cnt].src.doc = (һе. doc; 

set_curr_ext(the_data_H,e_cnt); 


сигг-ехі ло = e_cnt; 
e.cnt += 1; 
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(**the data. H).doc ID = {ће doc; /* update window */ 
(**the. data. НО. the. slot = slot ID; 
C(**the data НО. ехі cnt = e. cnt; 
(**the_data_H).dirty = true; 
ext_active = true; 


/* so save extents */ 


jac_err = ext writeCTextH, 
(**TextH).selStart, 
((**TextH).selEnd - (**TextH).selStart), 
the_doc, 
h_check, 
& the_ed); 


edd.displey-cmdCcurr.ext no, e cnt); /* update menu */ 


else /* IAC alert here */ 


NumToString (Clong)iac_err, &err_str); 
РагапТехі (&err_str, “Hot Сору”, nil, nil); 
item. hit = StopAlertCIAC_ERR_ALRT, nil); 


else /* already-in-extent alert */ 


ParamText (“\“already-in-extent\"”, “Hot Сору”, nil, nil); 
item hit = StopAlertCIAC ERR ALRT, nil); 


) 


/** 

* Routine: do_hotPaste 

x 

* This routine is responsible for completing а new depend- 
ency and notifying the IAC driver. It is called primarily by 
the “target” program. The dependencies are stored in the array 
in ascending sequence to makeupdating simpler. See the header 
for poll_iac() for details. */ 


8 define . SEC. .. Main 
void do-hotPasteC) 


( 

win_dataH the. data. H; 
TEHandle TextH; 
extentH the extH; 
exTeble ext.recs; 
long the. doc; 


/* data associated with a window */ 
/* The TextEdit handle */ 
/* handle to extent block */ 


/* local copies due to memory mashing */ 


short slot ID, h check; 

short e_cnt, startt; 

short the_ed; 

short item hit; /* error processing */ 
$tr255  err.str, str2; 

short i = Ø; 

short іас-егг = noErr; 

Boolean in_extent = false; 


/* sets “current extent” */ 
/* update ‘Links’ menu */ 


extern Boolean chk.extent(); 
extern void add-display. стас); 


extern Boolean ext.active; 


the_data_H = (win .dataH) GetWRefCon CmyWindow); 


the_extH = C**the. data. НО. the extents; 

TextH - (**the_data_H).wind_TEH; 

Slot_ID =  (**the. data. HD. the. slot; 

e.cnt = C(**the. data. H2 .ext. cnt; 

the .doc = ПВ; /* just link to “available” */ 
h-.check = 0; 


" Clchk extentCTextH, the c extH, e_cnt)) 


іас_егг = iac.complete dependency(&the doc, &slot 10, 
&h_check ); 
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if Сїас-егг == noErr) /* save “location” in TERec as 
extent */ 


(**the data. H2. the slot = slot ID; /* update window */ 

ext active = true; 

startt = (**TextH).selStart; 

SetHandleSize (CHandle)the_extH, sizeofCextent) * 
Ce-cnt* 125; 


/* walk extent table to find entry to insert BEFORE */ 
ext recs = *the extH; 
while Ci<e_cnt) 


if С Cext recs[il.ext.strt220) /* at end of table */ 
|| Cext_recslil.ext_strt»startt) ) /* table entry 
bigger */ 


( 
/* move tail of table to make space */ 
BlockMove(&ext_recs[i], 
&ext.recs[i*11, 
Ce_cnt - i) * sizeof Cextent)); 
break; 


else 


1 += 1; 

} 
} 
ext.recs[iJ.hat check = h_check;/* fill table entry */ 
ext. recs(il.ext. strt = (**TextH).selStart; 
ext.recs(il.ext end = (**TextH).selEnd; 
ext .recs[il.src.doc = (һе doc; 
set. curr extCthe. data. H, i); 


/* now read data from newly connected link */ 
the_ed = 0; 
їас_егг = ext_read(myWindow, &the_ed, i); 


extent_count += 1; 
curr_ext_no = i; 
C**the. data HD.ext cnt = e_cnt + 1; 
(**the_data_H).dirty = true; 
add_display_cmd(i, extent. count); 


) 


else 


/* global count */ 
/* update menu */ 


NumToString (Clong2iac.err, &err.str); 
РагапТехі C&err.str, “Hot Paste”, nil, nil); 
item hit = StopAlertCIAC ERR ALRT, nil); 


else /* already-in-extent alert */ 


ParemText (^Malready-in-extent V^, “Hot Paste’, nil, 
nil); 
tem hit = StopAlertCIAC ERR. ALRT, nil); 


) 
) 
Listing: Edit.rtins.c 


/*xxx 
x 


*These ere the routines needed for the actual text-editing 
functions. They are arranged alphabetically for ease of 
finding them. */ 


include «types.h? 
include <errors.h? 
include <memory.h? 
include <packages.h> 
include <quickdraw.h> 
include «toolutils.h» 
include <fonts.h 
include «windows.h? 


$$ 3$ + + 3$ ш 
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include «dialogs.h»? 
include <menus.h? 
include <textedit.h> 
include <string.h> 
include «files.» 
include <resources.h> 


tt 12 + ese 


8 include <iac.h> 
я define PUBLIC extern 
Я include <Editor.h> 


/** 

* Routine: do_clear 

x 

х This is the routine that carries out the “clear” editing 
function. It uses the normal TE routine to manipulate the 
text. In addition, it checks the source extents to see if any 
of them are affected by it, and if so,it will post the changed 
extent to the IAC driver for everybody else’s use. */ 


* define —SEG— Main 
void do_clear() 


short this_ed; 
short hit.ext; 
short 15 

short strt, endd; 
win_dataH the data. H; 


/* edition (updated) */ 
/* extent affect by this call */ 
/* scratch */ 
/* range in TE record */ 
/* data associated with a window */ 


extentH the_extH; /% handle to extent block */ 
extentP extP; 

TEHandle — TextH; /* The TextEdit handle */ 

Handle ext.data; /* data for extent */ 

short іас_соде = noErr; /* result from IAC call */ 
Boolean in-extent = false; 

Boolean ext killed = false; 


extern Boolean chk extent(); 
found */ 
extern voidkill.extent(); 


/* sets "current extent^ if 


/* get necessary handles, etc. set up */ 
the_data_H = (win dateH) GetWRefCon CmyWindow); 
TextH - (**the. data. H5 . wind. TEH; 

the_extH = (**the_data_H). the extents; 


/* Check extents before actually cutting. Remember which one 
and we^ll update the edition after doing the delete... */ 

in-extent = chk extentCTextH, the extH, 
C(**the. data. H2. ext. cnt); 


TEDelete (TextH); 

(**the. data. HD.dirty = true; 

/* if needed, write revised extent to IAC driver */ 

if Cin cextent) /* this delete effected the extent */ 


( 


/* adjust range for extent */ 


/* If the entire extent was removed, tell IAC driver */ 
Ü (ехі killed) 


іас-соде = iac_remove_dependency((**the_data_H).doc_ID, 
(**the_data_H). the. slot, 
curr ext .hat check); 

kill_extent(); /* always removes current extent */ 


else /* write to driver */ 


this_ed = curr- ext .ed. level; 

/* data setup here */ 

1ас_соде = iac write. dataCC**the. data. H).doc 10, 
curr ext .hat check, 
&this-ed, 
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1, 
ext. data); 
/* now adjust extent */ 


) 
) 


/** 

ж Routine: do_copy 

x 

* This is the routine that carries out the “copy” editing 
function. It uses the normal TE routine to manipulate the 
text. */ 


8 define . SEC... Main 
void do. copyCO 


( 

short this_ed; /* edition Cupdated) */ 
short 1, /* scratch */ 

short strt, endd; /* range іп TE record */ 


win.dataH (һе data.H;  /* data associated with a window */ 


extentH the_ex tH; /* hand to extent block */ 
extentP extP; 

TEHandle Техн; /* The TextEdit handle */ 
Handle ext_data; /* data for extent */ 

short jac_code = noErr; /* result from IAC call */ 
Boolean in-extent = false; 


extern Boolean chk extent(); /* sets “current extent” */ 
/* get necessary handles, etc. set up */ 
the_data_H = (win_dataH) GetWRefCon CmyWindow); 
TextH = (**the_data_H).wind_TEH; 
the_extH = (**the_data_H). the extents; 
in_extent = chk_extent(TextH, the_extH, (**the_data_H).ext_cnt); 
ТЕСору (TextH); 


/** 

* Routine: do_cut 

x 

х This is the routine that carries out the “cut” editing 
function. It uses the normal TE routine to manipulate the 
text. In addition, it checks the source extents to see if any 
of them are affected by it, end if so,it will post the changed 
extent to the IAC driver for everybody else's use. */ 


8 define .. SEC... Main 
void do_cut() 


( 

short this. ed; /* edition Cupdated) */ 
short hit ext; /* extent affect by this */ 
short i; /* scratch */ 

short strt, endd; /* range in TE record */ 


win_dataH the data. H;  /* data associated with a window */ 


extentH the_ex tH; /* hand to extent block */ 
extentP extP; 

TEHandle — TextH; /* The TextEdit handle */ 
Handle ext data; /* data for extent */ 

05Егг әп егг; 

short іас_соде = noErr; /* result from IAC call */ 
Boolean in-extent = false; 

Boolean ext_killed = false; 


extern Boolean chk extent(); /% sets “current extent” */ 


extern voidkill_extent(); 
/* get necessary handles, etc. set up */ 


the. data. H = (win. dataH? GetWRefCon CmyWindow); 
TextH = (**the. data. H5. wind. TEH; 
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the extH = (**the. data. HD. the extents; 


/* Check extents before actually cutting. Remember which one 
and we'll update the edition after doing the cut... */ 
in-extent = chk extent(TextH, the. extH, C** the. data HD .ext cnt); 

TECut (ТехіН); 

(**the_data_H).dirtu = true; 


/* if needed, write revised extent to IAC driver */ 
if Cin. extent) /* this cut affected the extent */ 


/* adjust range for extent */ 


/* If the entire extent was removed, tell ТАС driver */ 
и Cext. killed) 


1ас_соде = iac remove. dependencyCC**the. data. H2 .doc. ID, 
(**the_data Н). the. slot, 
curr- ext һа check); 

kill_extent(); /* always removes current extent */ 


else /* write to driver */ 


HLockCCHandle) TextH); 

/* data setup here */ 

an_err = PtrToHand (&(**TextH).selStart, &ext_data, 

(long? curr_ext.ext_end - curr_ext.ext_strt + 1); 

HUnlockCCHandle) TextH); 

this_ed = curr_ext.ed_level; 

1ас_соде = iac_write_data((**the_data_H).doc_ID, 
curr_ext .hat check, 
&this_ed, 1,ext_data); 

) /* end else */ 
} /* end in_extent */ 


/жж 
* Routine: do_key 
x 


х This is the routine that handles normal typing. It does 
NOT notify the IAC driver after every keystroke. */ 


8 define . SEG. . Main 


void do_key(msg) 
long msg;  /* event record message field */ 
( 
win.dataH (һе баба Н;  /* data associated with a window */ 
extentH the. extH; /* hand to extent block */ 
TEHandle — TextH; /* The TextEdit handle */ 
char the. ch; 
short e_cnt; 
Boolean in_extent = false; 


extern Boolean chk_extent(); 


#def ine charCodeMask 0х000000ҒҒ 
/*copied from event.h to conserve space */ 


/* get necessaru handles, etc. set up */ 
the_data_H = (win_dataH) GetWRefCon (muWindow); 
TextH = (**the_data_H).wind_TEH; 

the_extH = (**the_data_H). the_extents; 

the_ch = (char) (msg & charCodeMask); 

e_cnt = (**the_data_H).ext_cnt; 


in_extent = chk_extent(TextH, the_extH, e_cnt); 
TEKeu(the_ch, TextH); 
(**the_data_H).dirtu = true; 


/* now adjust extent if necessaru */ 
if Cin_extent) 
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( (the_ch==BS) /% backspace - shrink extent */ 


curr.ext.ext end -= 1; 
else /* insertion - expand extent */ 


curr.ext.ext.end += 1; 


ах 

* Routine: do_paste 

ж This is the routine that carries out the “paste” editing 
function. It uses the normal TE routine to manipulate the 
text. In eddition, it checks the source extents to see if any 
of them ere effected by it, and if so,it will post the changed 
extent to the IAC driver for everybody else's use. */ 


* define . SEG... Main 
"disc mn 


short this. ed; /* edition Cupdated) */ 


short hit. ext; /* extent affect by this */ 

short i /* scratch */ 

short delta; /* change in extent size */ 

short strt, endd; /% range in TE record */ 

win.dataeH the.data.H; /* data associated with а window */ 
extentH the. extH; /* hand to extent block */ 

TEHandle — TextH; /* The TextEdit handle */ 

Handle ext_data; /* data for extent */ 

short іас_соде = noErr; /* result from IAC call */ 
Boolean in-extent = false; 


extern Boolean chk extent );  /* sets “current extent” */ 
/* get necessary handles, etc. set up */ 

the_data_H = (win dataH) GetWRefCon CmyWindow); 

TextH = (**the_data_H).wind_TEH; 

the_extH = (**the_data_H). the_extents; 


/* Check extents before actually cutting. Remember which one 
and ие’11] update the edition after doing the paste... */ 

in-extent = chk.extent(TextH, іһе ехін, 
(**the_data_H).ext_cnt); 


TEPeste (TextH); 
(*%the_dataH).dirty = true; 


/* if needed, write revised extent to IAC driver */ 
if Cin_extent) /* this paste affects the extent */ 


/* adjust range for extent */ 
/* write to driver */ 
this.ed = curr_ext.ed_level; 
/* data setup here */ 
іас-соде = iac_write_data((**the_data_H).doc_ID, 
curr ext һа check, 
&this_ed, 1, ext. date); 


curr_ext.ext end += delta; 
curr.ext.ed level = this. ed; 


/* now updete extent */ 


) 
) 


/** 

x Routine: kill_extent 

ж This removes the current extent from the table and 
compresses the table. The count end "active flag” are also 
updated. */ 


* define . SEG. . Main 
voidkill_extent() /* always removes current extent */ 
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( 

win.dataH the_data_H; 
extentH the_extH; 
exTable ext.recs; 
long the. doc; 


/* data essociated with a window */ 
/* handle to extent block */ 


/* local copies due to memory mashing */ 


short slot ID, h.-check; 

short е-спі, startt; 

short 1; 

short 1ас_соде = noErr; /* result from IAC call */ 


extern Boolean ext active; 

the_data_H = Cwin_dataH) GetWRefCon (muWindow); 
the_extH =  (**the. deta. HD). the extents; 

e_cnt = (**the_data_H).ext cnt; 

startt = curr.ext.ext.strt; 


ext recs = *the_extH; 
for (1=0; i<e_cnt; 1++) 


/* point to table base */ 


if Cext.recsLil.ext.strt == startt) /* found current 
extent */ 


jac_code = iac remove dependency(CC**the. data. H) doc. ID, 
(**the. data. H5. the. slot, 
ext. recsLil.hat check); 
BlockMoveC&ext recs(i*1], /* move tail down */ 
&ext recs[i], 
(e_cnt-i)*sizeof (extent)); 
(**the_data H).ext_cnt -= 1; 
(**the_dataH).dirty = true; 
break; 


) 


ext_active = false; 


Listing: IAC.c 


/ххх 
х File: IAC.C 
* Package: Inter Application Communications 


* Description: This is the interface package to the driver for 
* the use of application programs. 

* Author(s): 

*FEA (6/19/88 */ 


include 
include 
include 


" (types .h) 
в 

tt 

® include 

н 

8 

в 


‹{11ев.һ› 
‹тетогу.һ› 
«osutils.h? 
(serial.h> 
‹їас.һ› 
«dialogs.h? 


include 
include 
include 


8 define MIN.BLK.SIZE 0хС 
# define DEBUG false 
8 define IAC_ERR_ALRT 257 


static short iac.ref num; 


/** 

х Routine: iac open 

* The IAC driver is opened by this call and the ioRefNum 
saved so it doesn’t need to be passed with all calls. A null 
value is returned if the open is successful; otherwise the 
operating system error is returned. */ 
short iac_open() 


( 

SysEnvRec theWorld;/* ALMOST complete knowledge about world */ 
THz s_ZoneP, a.ZoneP; /* so can check zone adjacency */ 
05Егг {ће_егг; 
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short result = 0; 
the_err = SysEnvironsC1, &theWorld); 
^ CtheWorld.systemVersion < 0х0420) /* too early! */ 


result = EARLY.SYS; /% “no multifinder^ */ 


else 


/*check for multifinder active by checking if system zone is 
adjacent to application zone, which never happens under 
MultiFinder. */ 


s.ZoneP = SystemZone(); 

a_ZoneP = ApplicZone(); 

if € CClong) s_ZoneP->bkLim + МІМ.ВІК 517Е) == (long) 
oe ) 


result = EARLY_SYS; /% zones adjacent - no MFinder */ 


else /* now try to actually open the IAC driver */ 


SysBeepC 1); 
result = OPENDRIVER(C*\p.IAC’, &iac_ref_num); 


return(result); 


/** 

* Routine: iac_add_dependencyz 

* This is used to inform the ТАС driver that а new depend- 
ency has been established and should be added to its internal 
tables. А null value is returned if the open is successful; 
otherwise the operating system error is returned. */ 


short iac_add-dependency(doc_id, slot id, hat.check, edition) 
long *doc_id; /* identifies source document (permanent) */ 
short *slot id; /* identifies source document (session) */ 
short *hat check; /* extent identifier */ 
short *edition; /* how many times extent has changed 
(session) */ 


10Param the_blk; 
05Егг the-err; 
struct ( 


short func; 
long doc. id; 
short slot. id; 
short hat check; 
short edition; 

) mu-params; 


* if DEBUG 
return(the_err=noErr);  /* short circuit for testing */ 

® endif 
my_params.func = 1; /* set up private parameter block */ 
my_params.doc_id = *doc.id; 
my_params.slot_id = *slot_id; 
my-perams.hat check = *hat check; 


the-blk.ioCompletion = nil; /* set up driver parem block */ 
the-blk.ioRefNum = iac-ref num; 

the-blk.ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof (my. parems?; 

the-blk.ioPosMode = fsFromStart; 

the-blk.ioPosOffset = 0; 

іһе-егг = PBWriteC&the blk.qLink, false); 

/* add the dependency */ 
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if (the_err == noErr) — /* update output parameters */ 
*doc-id = my.parems.doc. id; 

*slot id = my. perems.slot 14; 

*hat. check = my. parems.hat. check; 

*edition = my_params.edition; 


return(the_err); 


хх 

* Routine: iec-complete dependency 

* This is used to inform the ТАС driver of а document that 
is interested in а particular dependency. А null value is 
returned if the open is successful; otherwise the operating 
system error is returned. */ 


short iec complete dependency(doc.id, slot id, hat check) 
long *doc_id; /* identifies source document (permanent) */ 
short *slot_id; /* identifies source document (session) */ 
short *hat check; /* extent identifier */ 


ІОРагат the_blk; 
05Егг the_err; 
struct ( 


short func; 

long doc_id; 

short slot_id; 

short hat check; 
} my_params; 


® if DEBUG 
return(the_err=noErr);  /* testing without MF */ 

8 endif 
ny-parems.func = 2; /* set up private parameter block */ 
my_params.doc_id = *doc_id; 
my_params.slot_id = *slot_id; 
my-params.hat check = *hat check; 


the-blk.ioCompletion = nil;/* set up driver param block */ 
the_blk.ioRefNum = iac-ref num; 

the_blk.ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof (my_params); 

the_bik.ioPosMode = fsFromStart; 

the-blk.ioPosOffset = 0; 

{ће_егг = PBWriteC&the.blk.qLink, false); 

if (the_err == noErr) — /* update output parameters */ 
*doc_id = ту params.doc id; 

*slot_id = my_params.slot_id; 

*hat_check = my_params.hat—check; 


return(the_err); 


) 


/** 
x Routine: iac remove. dependency 
x 


х This is used to inform the IAC driver that а document is 
no longer interested in а particuler dependency. If the 
document is the originalsource all “targets” will be informed 
that there is no longer апу such extent; if all targets lose 
interest the source will be informed that itno longer needs 
to updete the extent. */ 


short iac_remove_dependency(doc_id, slot. id, hat check) 
long doc. id; /* identifies source document (permanent) */ 
short slot id; /* identifies source document (session) */ 
short hat check; /* extent identifier */ 
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10Param the_blk; 
05Егг іһе-егг; 
struct ( 


short func; 

long doc. id; 

short slot id; 

short hat check; 
) my_parans; 


# if DEBUG 
return(the_err=noErr ); 
® endif 


/* testing without MF */ 


my_params.func = 3; /* set up private parameter block */ 
mu-params.doc-id = doc. id; 

my-perems.slot.id = slot id; 

my-parems.hat check = hat check; 


the-blk.ioCompletion = nil; /* set up driver param block */ 
the-blk.ioRefNum = iac-ref num; 

the. blk.ioBuffer = &my_params; 

the blk.ioReqCount = sizeof (my_params); 

the-blk.ioPosMode = fsFromStart; 

the.blk.ioPosOffset = 0; 

іһе-егг = PBWriteC&the blk.qLink, false); 


returnCthe. err); 


) 


/** 

x Routine: iac-available dependency 

x 

x This sets the indicated extent as the “available extent” 
to be used as the source for future defaulted 

"complete .dependency^ calls. */ 


short iac_available_dependency(doc_id, hat check) 


long doc. id; /* identifies source document (permanent) */ 
short hat check; /* extent identifier */ 


10Param the_bik; 
05Егг {ће_егг; 
struct ( 


short func; 

long doc. id; 

short hat.check; 
} ny-params; 


# if DEBUG 
return(the_err=noErr ); 
8 endif 


/* for testing without MF */ 


my_perams.func = 4; /* set up private parameter block */ 
my_params.doc_id = doc_id; 
my_params .hatucheck = hat check; 


the-blk.ioCompletion = nil; /* set up driver param block */ 

the. blk.ioRefNum = iac.ref num; 

the.blk.ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof (my_params ); 

the-blk.ioPosMode - fsFromStart; 

the-blk.ioPosOffset = 0; 

the_err = PBWriteC&the. blk.qLink, false); /* this depend- 
епсу is now “available” */ 


returnCthe. err); 
/** 
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x Routine: iac_status 

x 

* This allows the application program to find out what's 
going on. */ 


short iac status(slot id, vers id, doc_count, extent count) 

short slot id; /% identifies the inquiring document 
(session) */ 

short *vers id; /* driver уегбіоп%100 */ 

short *doc.count;  /* count of active documents */ 

short *extent count; /* count of extents relevant to 
inquiring doc */ 


( 

ІОРагат the. blk; 
OSErr the_err ; 
struct ( 


short func; 

short slot id; 

short vers_id; 

short doc_count; 

short extent count; 
) my_params; 


# if DEBUG 
return(the_err=noErr);  /* for testing without MF */ 

8 endif 
my-parems.func = 5; /* set up private parameter block */ 
my-params.slot id = slot. id; 
the.blk.ioCompletion = nil; /* set up driver param block */ 

the-blk.ioRefNum = iac.ref num; 

the.blk.ioBuffer = &my_params; 

the.blk.ioReqCount = sizeof (my. params); 

the blk.ioPosMode = fsFromStart; 

the. blk.ioPosOffset = 0; 

the.err = PBRead(&the blk.qLink, false);/* read IAC status*/ 

if (the_err == noErr) /* update output paremeters */ 

*vers_id = my.params.vers. id; 

*doc.count = mg-params.doc. count; 

*extent count = my.params.extent count; 


return(Cthe err); 


) 


/** 

х Routine: iac-census 

x 

* This provides identifying info for all registered extents. 
х/ 


short iac-censusCextent. count, extent info) 
short *extent. count; /* count of extents registered */ 
info.tblP extent. info; /* Ptr to table of info for each 
extent */ 


( 
ГОРагат the. blk; 
05Егг {ће_егг; 
short i; 
struct ( 
short func; 
short extent. count; 


info_rec extent inf o[ MAX EXTS 1; 
) my-parems; 


® if DEBUG 


return(the_err=noErr);  /* testing without MF */ 
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Я endif 


my_params.func = 6; /* set up private parameter block */ 
the-blk.ioCompletion = nil; /* set up driver param block */ 
the blk.ioRefNum = iac.ref num; 

the. blk.ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof (my. params); 

the-blk.ioPosMode = fsFromStart; 

the-blk.ioPosOffset = 0; 

the_err = PBRead(kthe_blk.qLink, false);/* IAC status */ 


if (the_err == noErr) /* update output parameters */ 


*extent count = mu-params.extent_count; 
BlockMove (&my params.extent info(2], 
(Ptr) extent info, 
(long) my_params.extent_count * sizeof Cinfo_rec)); 


returnCthe. err); 


/** 
x Routine: iac.write data 


* This updates the data for the specified extent, resulting 
іп а new change level. */ 


Short iac.write data(doc id, hat. check, edition, fmt. count, 
ext. data) 
long doc. id; /* identifies source document (permanent) */ 
short hat check; /* extent identifier */ 
short *edition; /* how many times extent has changed 
(session) */ 
short fmt count; /* number of formats being written */ 
Handle ext.data; /* Handle to actual data */ 


( 

IOParam the. blk; 
OSErr the_err ; 
struct ( 


short func; 

long doc. id; 

short hat check; 

short edition; 

short fmt count; 

Handle the. dataH; 
) my_params; 


х if DEBUG 
return(the_err=noErr ); 
8 endif 


/* for testing without MF */ 


му-рагатз.Гипс = 7; /% set up private parameter block */ 

my_params.doc_id = doc.id; 

my-perams.hat check = hat. check; 

my-params.fmt count = fmt. count; 

my-perems.the.dataH = ext. data; 

the-blk.ioCompletion = nil; /* set up driver param block */ 

the-blk.ioRefNum = iac.ref num; 

the_bik. ioBuffer = &my_params; 

the-blk.ioReqCount = sizeof (my_params); 

the_blk.ioPosMode = fsFromStart; 

the-blk.ioPosOffset = Ø; 

the.err = PBWriteC&the blk.qLink, false); /* update 
dependency */ 


if (the_err == noErr) — /* update output parameters */ 


Xedition = my_params.edition; 
return(the_err); 


/** 
x Routine: 1ас_геад_да{а 


© The Definitive MacTutor, Vol. 4 


* This is used to retrieve the actual data for the latest 
change_levelfor the specified extent. The IAC driver will 
record that the inquiring document has read the data. ext_data 
will be resized by the driver to hold the data. */ 


short iec.read data(doc id, slot id, hat check, edition, 
fmt pref,fmt code, ext data) 
long doc. id; /* identifies source document (permanent) */ 
short slot_id; /% identifies the source document (ses- 
sion) */ 
short hat check; /Х extent identifier */ 
short *edition; /*times extent has changed (session) */ 
longfmt_pref [3]; /* prefd formats, descendg desirability */ 
long *fmt code; /* format returned to caller */ 
Handle ext. data; /* Handle to actual data */ 


( 

І0Рагат the blk; 
05Егг the_err; 
struct ( 


short func; 
long doc_id; 
short slot_id; 
short hat_check; 
short edition; 
long fmt pref [3]; 
long fmt. code; 
Handle ext. data; 
) my. params; 


8 if DEBUG 
return(the_err=noErr); 
8 endif 
my_params.func = 8; /% set up private parameter block */ 
my-params.doc-id = doc_id; 
my-params.slot id = slot. id; 
my-params.hat check = hat check; 
my-parems.edition = *edition; 


/* for testing without MF */ 


my-params.fmt.pref(Q] = fmt_pref [8]; 
my-params.fmt.pref[1] = fmt_pref[1); 
my_params.fmt_pref(2] = fmt_pref (21; 


my-params.ext data = ext data; 

the-blk.ioCompletion = nil; /* set up driver param block */ 
the-blk.ioRefNum = iac.ref num; 

the. blk.ioBuffer = &my_params; 

the. blk.ioReqCount = sizeof (my. params); 

the-blk.ioPosMode = fsFromStart; 

the-blk.ioPosOffset = 0; 

the_err = PBRead(&the.blk.qLink, false);/* read the data */ 
if (the.err == noErr) 


Xedition = my_params.edition; 
*fmt_code = my_params.fmt_code; } 
return(the_err); 


) 


Listing: SysEnvs.a 
; Glue for SysEnvirons that was skipped by Apple 
; F. Alviani 


; 1/88 
INCLUDE ‘ТВАРЗ.А’ ;Include Memory manager macros. 
PRINT ON 

SYSENV IRONS FUNC EXPORT 
movea. 1 4Csp2,80 ;аб contains ptr to world record 
move .W 8Csp2,d0 ;90 contains desired version 
-SysEnv irons 
moves. | (sp)+,a8 ;get return addr, remove 
Тег 6(sp),sp ;pop parameters 
move 00, Сөр) ;put result in place 


jmp (ай) ; до һопе 
DC.B 'SYSENVIR" 


END Sel 


C Workshop 
Tool Window Manager 


The Tool Window Manager 


Thomas Fruin is a graduate student of Computer Science at 
Leiden Universit, who also does study-related work for the two 
universities in Amsterdam, the University of Amsterdam and the 
Free University. He is the president and co-founder of VAMP 
(Vereniging Apple Macintosh Programmeurs), the main Dutch 
associationfor Macintosh programmers. Otherwise, he has done 
various odd Mac-related jobs to earn money, usually writing 
software (educational, communications, etc.). 

The Macintosh user interface has been enhanced with some 
interesting new features lately: tear-off menus, pop-up menus, 
hierarchical menus, window layers, color, and even a new name: 
human interface. While most of these additions are in the new 
ROMS and the latest System file, not everything has been dealt 
with by Apple. Most notably is the lack of code to support tear- 
off menus, the most recent novelty and pioneered by HyperCard. 
They are something you are going to have to code all by yourself 
(well, with a bit of help from others). Darryl Lovato addressed 
the problem of tearing off a menu first, followed by an in depth 
article by Don Melton and Mike Ritter. In my contribution I will 
concentrate on keeping windows (torn-off menus or otherwise) 
floating above the others on your desktop, by presenting an 
alternative window manager - called the Tool Window Manager 
- that does all the work. 

While tear-off menus are new to the Mac, floating windows 
are not. For several years now there have been applications 
putting their tools, patterns and other wares in these little win- 
dows, like FullPaint and PageMaker to name just two. Tool 
windows are a tricky business though, and it takes some careful 
planning to get everything right. Even commercial programs 
make mistakes at this (see the sidebaron the bugs in FullPaint and 
MacPaint). 


Tool Windows Have a Special Appearance 

First of all, since tool windows always lie on top, there is no 
distinction between an active or inactive tool window. This 
means that the tool should either have no title bar (like in 
FullPaint), or a title bar that never changes its appearance (like in 
HyperCard or Claris MacPaint). The latter case requires a special 
window definition function. This is not the subject of this article, 
however, since window definition functions have already been 
dealt with by MacTutor. Besides, you can cheat by experiment- 
ing with the WDEF for tool windows in the new MacPaint. Just 
copy WDEF 34 from your copy of MacPaint with ResEdit and 
paste itin your own application. Of course you cannot distribute 
і... (but you knew that, didn't you?) 

Don Melton and Mike Ritter's comments on the user inter- 
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face guidelines for tool windows, and especially their additions 
to the guidelines, are a good idea. Since the article came out, I 
have modified my manager to incorporate these additions: when 
a non-application window is brought to the front (usually a desk 
accessory), my manager will unhighlight all the tool windows. 
Whenthat window disappears, all the tools are highlighted again. 
I also added this behavior when a modal dialog window is 
brought to the front, because it seems to make sense. Finally, the 
unhighlighting of the tool windows also takes place when an- 
other application is activated under MultiFinder. It is up to the 
application that uses the Tool Window Manager to hide the tool 
windows when the application is juggled out, since it may not 
always want to hide the tools (one of them may be some kind of 
status window, for example). 


Tool Windows or GhostWindows? 

Tool windows are also sometimes called ghost windows. 
This is probably due to the obscure GhostWindow low memory 
global that is mentioned in Inside Macintosh volume I, page 287. 
You had better forget about it. I'm notonly doing this as a public 
service (since Apple is discouraging people to use low memory 
globals), but also because it really doesn't help in our case. As 
inalmostevery part of Inside Macintosh, the information is there, 
but it takes some careful reading to understand what the para- 
graphisabout. Besides, GhostWindow will only let you have one 
tool window at a time, and we want to create as many tool 
windows as will fit in memory (it's ok with me if you only want 
two or three). So it seems the only way ош is a front end for all 
the Window Manager routines that could cause a tool window to 
become obscured. This is what I have written in the Tool 
Window Manager, or TWindow Manager for short. 


The Mad T Party 

The TWindow Manager is a set of 10 functions that replace 
calls to functions in the Window and Event Managers in your 
source file. Thesenew functions do someextra processing before 
they call the Window and Event Manager themselves. The 
names of these TWindow Manager routines are the same as their 
corresponding Window and Event Manager functions, except for 
aprefixed "T", asin TSelectWindow and TGetNextEvent. Their 
parameters are almost the same as the original functions, with a 
few slight modifications. See the explanations below for details. 
There are six categories of window manipulations that need to be 
replaced by TWindow Manager functions to work correctly with 
tool windows: (1) Adding windows to the desktop: use 
TNewWindow, TGetNewWindow and TShowWindow. (2) 
Removing windows: use TCloseWindow, TDisposeWindow 
and THideWindow. (3) Bringing lower windows to the top with 
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TSelectWindow. (4) Dragging with TDragWindow. (5) Utility 
functions you will need every now and then: TFrontWindow and 
the new TInitWindows and TGetWKind. (6) Event handling: 
TGetNextEvent. This last function is included, because activate 
and deactivate events are handled differently when there are tool 
windows about. Note that I did not mention resizing windows 
(yes, I’m mentioning it now, thank you). Amazingly, GrowWin- 
dow is smart enough to draw its grow outline below any windows 
that are lying on top of it. It’s always nice to have less work to 
do. 

There are three source files that go with this article. 
TWindows.c is the TWindow Manager itself, written in MPW C, 
and can be compiled into a separate module for later linking with 
your own program. TWindows.h is a file for inclusion by your 
program. It holds common data types and the TWindow function 
types. Your program will need this file if it wants to call 
TWindow Manager functions and use constants such as tool Kind 
and anyKind. Finally, TWindowTester.c (also in MPW C) is an 
example program that uses the TWindow Manager. It is a 
familiar ‘vanilla’ Macintosh program that lets you create normal 
and tool windows to experiment with, as may as you like (see 
figure 1). You can select and drag windows, and open desk 
accessories as well. (Note that I got the tool window definition 
function from MacPaint 2.0, as I described above. In the source 
I am distributing, the windows look more like FullPaint’s tools, 
because MacPaint’s defproc is not included.) The menus called 
Windows and Tools let you make any document window or tool 
invisible and visible again, even if it isn’t in front. I added these 
menus myself to test the robustness of the TWindow Manager. 
Note that you can’t do anything useful with TWindowTester 
(although you might derive great pleasure from opening, say, 100 
windows). For example, the scroll bars in the document windows 
don’t work. I just put them there so you can see that windows get 
activated and deactivated properly. 


Background Information, Utility Functions 

The TWindow Manager keeps tool windows and document 
windows apart by storing a special value in the WindowRecord’s 
windowKind field. This value is defined as the toolKind constant 
(equal to 30000) in the source file for TWindows. If you like, you 
can modify it to a value more suitable to your application, but 
there should be little conflicts as is. If any of the TWindow 
Manager functions wants to know what kind of window it is 
dealing with, it calls the utility function TGetWKind. This 
function is precisely for determining the windowKind value of a 
window. Why write a function for such a simple task? Well, 
TGetWKind doesn't just return the window's windowKind, but 
does some extra processing as well. If the window is a desk 
accessory window (with a negative windowKind), TGetW Kind 
will always return the constant systemKind (equal to -1). If the 
window is a dialog window, with windowKind equal to the 
toolbox constant dialogKind, TGetWKind only returns dia- 
logKind if the window is a modal dialog window. If the dialog 
is modeless, TGetW Kind returns the toolbox constant userKind 
(the toolbox constant for normal document windows). This is 
because modeless dialog windows behave almost exactly the 
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same as document windows, i.e. they lie behind tool windows. 
TGetWKind figures out what kind of dialog itis by examining the 
window's variation code and definition procedure. Window 
definition procedures have an (optional) header embedded in 
their code that holds information like the WDEF's resource ID 
(see Technical Note 110 for more information about WDEFs - 
and make sure you have the “real” 110). The dialog is considered 
modeless if its window is a document window: this is when the 
WDEF's resource ID is zero and the variation code is equal to 
documentProc, noGrowDocProc or zoomDocProc. To play it 
safe, I let TGetWKind also check if the resource type in the 
header is really *WDEF'. If the WDEF doesn't have a header 
(like the MacPaint tool window for example), it's extremely 
unlikely that there will be а ‘WDEF’ string embedded at that 
particular position in the code. 

The Window Manager in the Macintosh ROM has (as far as 
I can determine) only one global variable dealing with window 
positions, called WindowList - at location $906. It holds the very 
first window in the window list. By comparison, my TWindow 
Manager has three position globals of its own: frontToolWin- 
dow, backToolWindow апа frontDocWindow. FrontToolWin- 
dow points to the frontmost visible tool window, backTooIWin- 
dow to the backmost visible tool window, and frontDocWindow 
to the frontmost visible document window. Two other global 
variables I use mimic the CurActivate ($A64) and CurDeactive 
($A68) low memory globals in the Macintosh: toBeActivated 
and toBeDeactivated. They hold the real windows that need 
activating and deactivating, and my TGetNextEvent takes them 
into account when it returns activate events. They are set by 
various TWindow Manager routines whenever activate events 
need to be posted. Finally I have two utility global variables, 
firstRgn and secondRgn. All these seven globals need to be 
initialized by the TInitWindows function, before you start using 
any functions in the TWindow Manager. 

TFrontWindow is my replacement for FrontWindow. You 
can specify a window type in the windowKind parameter (note 
that Front Window has no parameters at all). This window type 


Figure 1: The TWindowTester Application 
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is one of the constants tooIKind, userKind ог anyKind. Usually 
you will want to call TFrontWindow with windowKind equal to 
userKind; it will then return the frontmost visible document 
window (the active window), ignoring any tool windows that 
may be lying above it (unless there is a desk accessory or modal 
dialog on top - it then returns the DA's or dialog's window). 
Calling TFrontWindow with windowKind equal to toolKind 
returns the frontmost visible tool window (again taking DAs and 
dialogs into account). When you call TFrontWindow with 
anyKind as the parameter, it behaves exactly like the original 
FrontWindow function - it simply returns the frontmost visible 
window. 
Selecting Windows 

I'msaving the subjects of adding and removing windows for 
later, because they are the trickiest ones to handle. TSelectWin- 
dow, by comparison, is much easier. Here, the main problem is 
to bring a document window to the "front" while keeping it 
behind any tool windows that may be visible. Apple, in its 
infinite wisdom, already has a function that almost does this: it's 
called SendBehind and it's listed on page 1-286 in Inside Macin- 
tosh. You use it to move a window closer to the front (ah, so that’s 
why it’s called SendBehind), and specify the window behind 
which your window should be moved. In our case this will 
usually be the backmost tool window. Note what Inside Macin- 
tosh has to say about this: “If you’re moving theWindow closer 
to the front (that is, if it’s initially even further behind behind- 
Window), you must make the following calls after calling Send- 
Behind: 


wPeek = POINTERC theWindow ); 
PaintOneC wPeek, wPeek^.strucRgn ); 
CalcVisC wPeek ); 


This means that you have to do some low-level stuff, 
because SendBehind isn't really meant to bring windows for- 
ward. PaintOne (5 pages further) is a routine that whitewashes 
the newly exposed part of the window. CalcVis (on the nextpage 
in Inside Macintosh) recalculates the window's visRgn. Unfor- 
tunately, it seems Apple goofed here. CalcVis only recalculates 
the visRgn of one window, while we need to recalculate the 
visRgns of all the windows following our window. Apple makes 
up for this, though, by supplying us with the routine Calc VisBe- 
hind (on same page as CalcVis). This function does not only 
recalculate the visRgn of our window, but also of all the windows 
following it. If you're curious, try replacing CalcVisBehind by 
CalcVis and watch what happens on the screen (don't do this if 
you dislike making a mess of things). 

Another thing: the above call to PaintOne paints the whole 
window white, and not only the newly exposed part. Therefore, 
I'vecreated the utility function BringForward, that calls SendBe- 
hind, PaintOne and CalcVisBehind, and only repaints those 
newly exposed parts. BringForwardiscalled by TSelectWindow 
and many other routines in the TWindow Manager. 

If you look at the source code for TSelect Window, you'll see 
itdoes a lot more than just calling BringForward. This is because 
we have to take desk accessories into account. An open desk 
accessory will always lie above any tool windows when it is 
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active. If the user selects one of the document windows, it 
naturally comes to the front, but not until all of the tool windows 
have also been brought to the front (remember that they were 
lying behind the desk accessory). I’ve written another utility 
function for this, obviously called BringToolsForward. This 
function makes repeated calls to BringForward for each visible 
tool window. These calls it makes to BringForward have a 
special flag to tell it not to call CalcVisBehind each time. This 
is because CalcVisBehind is a relatively time-consuming func- 
tion. Once all the tool windows have been brought forward, 
BringToolsForward makes one final call to CalcVisBehind, 
recalculating all those changed visRgns at once. This speeds 
things up by about 30%, which is nice when you have alot of tool 
windows (at one time during testing, I created about 50). The 
speed bottleneck, however, seems to be SendBehind. I wish 
Apple would publish interfaces to the Layer Manager in Multi- 
Finder, because it has much more efficient ways of quickly 
moving windows to the front. Those aren't standard Window 
Manager functions working there ... 

Two other useful utility functions internal to the TWindow 
Manager are NextVisWindow and PrevVisWindow. They 
operate fairly straightforward, and do exactly what their names 
imply: NextVisWindow returns the next visible window, and 
PrevVisWindow returns the previous visible window in the 
window list, with respect to the window that gets passed to it. 
NextVisWindow and PrevVisWindow are used in various places 
in the TWindow Manager, including here in TSelectWindow. 


Dragging Windows 

TDragWindow replaces the standard toolbox function 
DragWindow. It lets you drag a document window, while 
ensuring that it doesn't obscure any tool windows that may be 
lying in front of it. Again, I am grateful to Apple for doing the 
dirty work: they wrote this useful low level function called 
DragGrayRgn (Inside Macintosh page 1-294) that pulls a gray 
outline of a region around. DragWindow actually calls Drag- 
GrayRgn, but in the wrong way (for our purposes). 

The first thing TDragWindow does is check if the user is 
holding down the Command key. It gets this information from 
the EventRecord that you pass it. (Note that TDragWindow 
wants you to pass an EventRecord as its second parameter, while 
DragWindow wants the point where the mouse was clicked.) If 
the Command key is not being held down, TDragWindow calls 
TSelectWindow to move the window to the front (while staying 
below any tool windows, remember?). Once that is done, we can 
call DragGrayRgn to move an outline of the window. This 
outline is the window's strucRgn, so we pass copy of the 
strucRgn to DragGrayRgn. DragGrayRgn needs some more 
parameters, like the point the mouse was originally clicked and 
the bounding rectangles for the drag, but they are pretty obvious 
from the documentation in Inside Macintosh. 

We have one last problem: how do we get DragGrayRgn to 
draw its outline below the tool windows? Aha, well, there's yet 
another low-level Window Manager function for that (I hope I'm 
not boring you). It's called ClipAbove, and Inside Macintosh 
says that "ClipAbove sets the clipRgn of the Window Manager 
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port to be the desktop intersected with the current clipRgn, minus 
the structure regions of all the windows in front of the given 
window.” Great. So all we have to do is set the current port to 
the Window Manager port, set its clipRgn to the whole current 
desktop, and call ClipAbove. Then we go ahead and call 
DragGrayRgn. You'll see that the gray outline gets drawn in the 
Window Manager port, and stays neatly below the tool windows. 
After dragging, we check if the user really did move the window 
by examining DragGrayRgn's result. If he did, we call MoveW- 
indow to actually move the window to its new position. And of 
course we restore the Window Manager port's clipRgn (since 
we've been messing with it), and reset the current port. 


Dealing With Activate and Deactivate Events 

Normally, the Window Manager in the Macintosh ROM 
posts an deactivate event when the frontmost window gets 
moved back, and a activate event when a window gets moved to 
the front. This won't work in our case, because our document 
windows never get moved to the front. They always stay behind 
our tool windows. But we still want selected document windows 
to receive (de)activate events, and preferably in the standard 
way: as events returned by some kind of TGetNextEvent func- 
tion. My solution was to copy the mechanism Apple uses: the 
Macintosh has two low memory globals, CurActivate and Cur- 
Deactive. GetNextEvent checks these two globals first, before it 
examines the event queue. If it finds that one of these globals is 
nonzero, it fills in the user's EventRecord with an activate event 
for the window pointed to by one of these globals. CurActivate 
holds a pointer to the window that needs to be activated, and 
CurDeactive a pointer to the window that needs to be deactivated. 
Deactivate events have a higher priority than activate events. 

My new TGetNextEvent does more or less the same, but 
instead it uses my globals toBeActivated and toBeDeactivated. 
(Please note that they are not in low memory, so don't worry 
about using them.) Whenever any routine in the TWindow 
Manager moves windows around, it updates these two globals. 
When TGetNextEvent gets called (as a replacement for GetNex- 
tEvent - writing TWaitNextEvent is left as an exercise for the 
reader), it checks these two globals and returns its own activate 
events back to the calling application. 

TGetNextEvent handles three types of situations. It calls 
EventAvail to see what kind of event is currently pending. (1) 
The first situation arises when there is a true (de)activate event 
pending. In that case, it gets the event with GetNextEvent (the 
real one). Dependingonthe type of event (activate or deactivate), 
itcompares the event's window with either the toBeActivated or 
the toBeDeactivated global. If the window the toolbox wants to 
activate is equal to toBeActivated, or the window it wants to 
deactivate is equal to toBeDeactivated, the toolbox is doing fine 
and there is nothing left for us to rectify. If toBeActivated or 
toBeDeactivated are nil, it means we didn't anticipate the acti- 
vate event. This is an important occurrence and happens when a 
desk accessory suddenly gets opened or closed. In this case we 
substitute our front document window (frontDocWindow) for 
the window that gets (de)activated; additionally, we call Hil- 
iteWindow to highlight or unhighlight the frontDocWindow’s 
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title bar, since that hasn't been done yet, and we call HiliteTools 
to unhighlight or highlight all the tool windows. HiliteTools is 
a simple utility function I wrote that traverses all the. tool 
windows, and calls HiliteWindow for each visible one. Oh yes, 
if there wasn't any document window open to pass the event to, 
we call TGetNextEvent again (recursively), thereby discard the 
current (de)activate event, and get a new event. After handling 
the event we reset toBeActivated or toBeDeactivated to nil and 
return. 

(2) The second situation occurs when Еуеп Ауа! does not 
return an (de)activate event and either toBeDeactivated or to- 
BeActivated is not nil. This means some action of the TWindow 
Manager generated an (de)activate event without the toolbox 
knowing about it (like when you call TSelectWindow to activate 
a window without bringing it completely to the front). The thing 
to do is to fill the caller's EventRecord with an activate event for 
the window in the toBeActivated or toBeDeactivated global. The 
call to WindowExists has to do with dialog windows: I'll get to 
that later. (3) The third and final situation occurs when 
EventAvail doesn't return an (de)activate event, and both to- 
BeActivated and toBeDeactivated are nil. There's nothing out of 
the ordinary to do here, so we simply call GetNextEvent and 
return the event. 

While I was debugging this routine, I discovered something 
I had not anticipated since it had not been mentioned in Inside 
Macintosh: now and then, activate events were being returned for 
desk accessories! I was expecting GetNextEvent to take care of 
this by calling SystemEvent to pass the event on to the desk 
accessory directly (see page I-442). To remedy this I included the 
extra test in TGetNextEvent on the type of window belonging to 
an activate event. If the window isn’t one of our (tool or 
document-) windows, we leave the event as it is. Another 
Surprise were the deactivate events that were being posted for 
invisible windows. But if you think about it, it makes sense. 
When you hide the front window, the toolbox moves the window 
behind it to the front and activates it. Should you make your 
hidden window visible again, it will appear behind the current 
frontmost window, and should thus appear deactivated. There- 
fore the deactivate event. It makes you realize a lot is happening 
behind the scenes ... 


Adding Windows 

At first I thought it would be easy to write front ends for 
functions like NewWindow and GetNewWindow. АП I would 
have to do was make sure that the calling application wasn’t 
trying to create new document windows in front of existing tool 
windows. I thought I could check this with a couple of nested if- 
else statements. I managed to put together some stuff, but it 
didn’t seem to cover everything. Whenever I thought about the 
code for a while, I would come up with a strange situation 
(usually in the bathroom, does that happen to you too?) that I 
hadn’t anticipated yet. Things went really wrong when I tried to 
write TShowWindow! There were so many different combina- 
tions of windows, I had to take a completely different approach. 
The important thing to realize is that once the application pro- 
gram starts creating new windows, or making windows visible, 
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these windows сап appear absolutely anywhere іп the window 
list. A document window could appear on top, with tools behind 
1. Or a desk accessory might turn up between a tool and a 
document window, which is also not allowed. When calling 
GetNewWindow or NewWindow, windows can turn up in the 
wrong place, because the caller can specify any position for the 
new window. When calling ShowWindow, things can go wrong, 
because you have very little control over what is happening with 
your invisible windows. OK,IadmitImake things worse myself, 
because the BringToolsForward function, for example, only 
moves visible tool windows, and leaves invisible tools scattered 
all over the window list. But itis more efficient to keep only the 
visible windows in their correct planes. We just have to be very 
careful when we make windows visible again. 

First of all, I changed my earlier TGetNewWindow and 
TNewWindow into very simple functions that do two things: (1) 
They create the window as specified by their parameters, but 
make itinvisible. They then set the window's windowKind field 
according to an extra TNewWindow or TGetNewWindow pa- 
rameter. This parameter is also called windowKind, and lets the 
application indicate if it wants a tool window or document 
window. (Remember that the TWindow Managers distinguishes 
tool windows by looking at the windowKind field in the Win- 
dowRecord.) But the important thing is that the window is 
always created invisible. (2) If the caller wants the window to be 
visible, I call the function TShowWindow afterwards. TShow- 
Window does the tedious work of making the window show up 
in an allowed position, and all the testing code is centralized in 
this one function. So how dol find out if the caller wants a visible 
or invisible window? Well, when the calling application uses 
TNewWindow it’s easy: I just examine the visible parameter. 
With TGetNewWindow I have do some extra work, because 
there is no visible parameter, but only a WIND resource. TGet- 
NewWindow reads the WIND resource manually with a GetRe- 
source call, and gets the visible field from there. While the 
resource is in memory, TGetNewWindow also reads the other 
fields from it, such as the title, goAwayFlag etc. It then calls 
ReleaseResource to get rid of the WIND template, and creates the 
window with a normal NewWindow call. 


Removing Windows 

Before I get into TShowWindow, I want to point out that 
removing windows is very similar to adding windows. 
TCloseWindow and TDisposeWindow are very simple func- 
tions that call THideWindow to hide the window and make sure 
the rest of the windows are still in allowed positions. They then 
get rid of the window data structures through the usual calls to 
CloseWindow and DisposeWindow. There is one tricky situ- 
ation though: suppose the window is the active one. THideWin- 
dow will then post a deactivate event for it in toBeDeactivated. 
If the window gets destroyed, that event will have to be removed. 
That’s why I check if the window is equal to toBeDeactivated, 
and if it is, clear toBeDeactivated. The toolbox does the same 
thing (hardly surprising, because that’s where I got the idea in the 
first place): CloseWindow and Dispose Window check CurDeac- 
tive and clear it if necessary. 
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So it all boils down to THide Window and TShowWindow - 
on to the next section, class. 


Hiding and Showing - Where Are We in the First 
Place? 

If you start thinking about it, many strange permutations of 
windows can occur on the desktop: desk accessories, tool win- 
dows, document windows, modal dialogs and modeless dialogs. 
Somehow, we have to keep the tools in front of the documents 
and modeless dialogs, while letting DAs and modal dialogs be on 
top from time to time. And any category of windows might be 
absent - suppose the application doesn’t have any tool windows 
visible? 

There may be many window permutations, but you will be 
pleased to hear the number is not infinite. In fact, there are 
precisely ten distinct positions a window can be in with respect 
to the other windows on the screen. (There may be more or less, 
depending on your own way of classifying windows.) Once you 
know in what position a particular window is, it’s very clear what 
you have to do when that window is hidden or shown. The utility 
function TGetWPosition finds out what this position is: 
THideWindow or TShowWindow pass it a window, and it will 
tell them in which of the ten places the window is. It returns one 
of the ten possible constants describing this position. Note that 
TGetWPosition works for both visible and invisible windows. 
Since these ten positions are central to understanding how 
THideWindow and TShowWindow work, let me list them for 
you (remember that our window can be visible or invisible, and 
can be either a tool-, document- or dialog window). You’ ll want 
to glance at figure 2 along the way. 


alone there are no other visible windows on the 
screen 
beforeDialog our window is completely in front, and 


the window behind it is a modal dialog 
beforeSystem our window is completely in front, and 
the window behind it is a desk accessory 


beforeTool 


beforeDocument behindFrontSystem 


behindSystem 


Figure 2: Window Positions 
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beforeTool our window is completely in front, and the 
window behind it is a tool window 

beforeDocument our window is completely in front, and 
the window behind it is a document window 

behindFrontSystem there are one or more desk accesso- 
ries in front, and our window is lying just behind them (but before 
any tool or document windows); it could be our window is the 
frontmost tool window 

betweenTools our window is lying among the tool 
windows; if it's visible, it could also be the last tool window 

behindToolsour window is lying behind all the tool win- 
dows, but in front of any document windows; if our window is a 
tool, it can only be invisible, otherwise it would be in the 
betweenTools position 

behindSystem this is really an obscure arrangement, 
and only exists when our window is invisible: there are no 
document windows, there is a tool in front, and the tools are 
followed by one or more desk accessories; our invisible window 
is lying behind the desk accessories 

betweenDocuments our window islying among the docu- 
ment windows; if it's a visible document window, it certainly 
isn't the frontmost one 

TGetWPosition starts with a pointer to the frontmost visible 
window, and works its way through the window list until it finds 
our window. While it's doing this, it keeps track of current 
window position. Once it hits our window, it returns this 
position. Notice that when our window is visible, TGetWPosi- 
tion really looks for the window preceding it. That way the 
algorithm works for both visible and invisible windows. Asa 
bonus you also get the windowKind of the frontmost window in 
one of the parameters. THideWindow and TShowWindow 
might want to look at this to see if there is a desk accessory in 
front. 


We've Found Our Place! 

Now everything falls into place. TShowWindow and 
THideWindow simply call TGetWPosition, and let three big 
Switch statements (the first if we are dealing with a tool window, 
the second for a document window/modeless dialog and a little 
one for a modal dialog) handle the nitty gritty details. We have 
a case for almost every window position. Some cases are the 
same (like hidinga tool in the positions alone and beforeSystem), 
while others are so obscure that they cannot possibly occur in 
each function (there is no case for hiding a window in the 
behindS ystem position). If you look at the source, you'll see that 
each case executes a small but different block of code. The code 
deals with things like setting the toBeActivated and toBeDeac- 
tivated globals, bringing tools forward with BringToolsForward, 
updating frontToolWindow, backToolWindow and front- 
DocWindow, and sometimes highlighting windows manually 
. with HiliteWindow and HiliteTools. Most cases are easy to 
follow, although there are a few complex ones. The behindTools 
case for a hiding a document window does a lot of things, so it is 

a nice example to illustrate how all of this works. 


An Example of Hiding a Window 
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When our document window is behindTools, it is obviously 
the frontmost document window (itis lying just behind the tools). 
This means we have to find the new document window (our 
window is going to be hidden). We call NextVisWindow with a 
windowKind parameter of userKind. This means NextVisWin- 
dow will return the next visible document window (or modeless 
dialog, because TGetWKind considers modeless dialogs the 
same as document windows). But suppose the next visible 
window is a desk accessory? That's why there is the other call 
to NextVisWindow. This call determines what the real first 
window behind ours is, regardless of the type of the window, 
because we use the anyKind parameter. We then hide our 
window with ShowHide. | 

If there is no window behind ours, we only have to post a 
deactivate event for our hidden window. If there is, there are two 
possibilities: it is a desk accessory - if behindWindow differs 
from frontDocWindow - or it is a document window, in which 
case behindWindow should be equal to frontDocWindow. А 
desk accessory will have to be brought completely to the front - 
if there isn't already a DA in front - with SelectWindow. Then 
something important: a document window that could be lying 
much further back (behind the DA) has to be brought forward, 
just behind the tool windows. Tools always “stick” to atleast one 
document window. This is what the BringForward call is for. 
Finally, if the window behind ours was nota DA, buta document 
window, we make it the active window by highlighting it and 
posting the necessary activate events. All of this only if there 
isn't a DA in front, of course. Phew! Rest assured that if you 
understood this, the rest of the cases are a piece of cake. 


TNewDialog, TGetNewDialog, TCloseDialog in 
TDisposDialog? 

Don't panic! I'm not going to write front ends for every 
manager in the toolbox. You will have to do a few extra things 
for dialogs though (especially to get the window behind it to 
deactivate properly). When you want to put up a new dialog, do 
the following: first call NewDialog or GetNewDialog to create 
the dialog, but make sure it is still invisible. Then call TShow- 
Window to make it visible. TShowWindow will ensure that the 
document window behind it gets deactivated properly, and that 
all the tools are unhighlighted. Chances are that you are already 
doing this (creating an invisible dialog, and showing it after- 
wards) to install a user item to boldly go where no man ... oops, 
to boldly outline the OK button in the dialog. To remove а dialog 
you should do something similar: call THideWindow to hide it, 
and CloseDialog or DisposDialog afterwards. 

You might remember that when a window gets destroyed, a 
possible pending deactivate event for it should be removed as 
well. Unfortunately, THideWindow posts a deactivate event in 
toBeDeactivated, but it never gets removed. Sure, CloseDialog 
and DisposDialog remove the toolbox's event in CurDeactive, 
but what about our own event? I suppose I could have written 
front ends for these Dialog Manager functions, but I think I've 
gone far enough as 15. So this is where the WindowExists 
function comes in (remember, I mentioned it back when I was 
discussing TGetNextEvent). As alastresort, WindowExists gets 
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called to make sure the window that needs deactivating still 
exists. If it doesn't, we call TGetNextEvent again to get a new 
event instead. 

The Point Of It АП 

The advantage of all this tedious, boring, dense and volumi- 
nous code is that you can forget it. Yes, go ahead and forget it. 
Once the TWindows.c module has been compiled, you can link 
it with your application and you won't have to worry about tool 
windows again. Just change your usual calls to the Window 
Manager into calls to the TWindow Manager. (See TWin- 
dowTester for examples). Whenever you create new document 
ortool windows, hide them, drag them around the screen, or bring 
them to the front, the TWindow Manager will do its utmost best 
to keep you happy by keeping those tools floating above your 
documents. 

There is far more information in the source files than I have 
mentioned here. Especially the sources on the source code disks 
have lots more comments and explanations than what would fit 
in the magazine. Still, I might have overlooked something. In 
that case (or for any not necessarily useful reason - what I mean 
to say is: I don't mind getting mail), you can always reach me at 
one of the addresses below: 


Thomas Fruin fruin@hlerulS5.BITNET 
Galgewater 38 thomas@ uvabick. UUCP 
2311 VZ LEIDEN dibs@ well.UUCP 
The Netherlands hol0066 on AppleLink 
2:508/15 on FidoNet 
Listing: TWindow.c 
/ x 
ж TWindows.c 
x 
* ( source of an extended Window Manager that 
* supports tool windows; these are windows 
* that always float on top, for palettes and 
* tools. 
x 
ж Written in MPW C 2.9 
x 
* Copyright Thomas Fruin 1988 
* All rights reserved. 
x/ 
/ x 
* TOOLBOX INCLUDES 
*/ 


include <Types.h> 
8include «Memory.h? 

8 include «Quickdraw.h? 
* include «Events.h? 
*finclude «WWindows.h? 

8* include «ToolUtils.h? 
* include «0SUtils.h? 

* include «Resources.h? 


/* 
* TOOLBOX 
*/ 

Qdef ine GrauRgn (*(RgnHandle *)0xOEE) 

"define WindowList  (*(WindowPeek *)0x9D6) 
x 


DEFINITIONS 


* DEFINITIONS 
x 


/% Def ines LONGINT, INTEGER, the windowKind 
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constants and the externally callable 
TWindow Manager functions. */ 


8include <TWindows.h> 
/* Result codes describing window positions, as 
returned by the function GetWPosition. */ 

"def ine alone 0 
8def ine beforeDialog 1 
8def ine beforeSystem 2 
define БеГогеТоо] 3 
"define beforeDocument 4 
8def ine behindFrontSystem 5 
#def ine betweenTools 6 
"idef ine behindTools T 
#def ine behindSystem 8 
#def ine betweenDocuments 9 


/* Miscellaneous */ 


"define deactivFlag 0 
8dgef ine noDrag -32768 
#def ine invisible false 


#def ine curVersion 1 

8define postponeCalc true 

#def ine normalCalc false 
x 


* TYPES 
*/ 

/* Тһе WINDData structure matches the structure 
of a WIND resource in а resource file. It 
is used to access the various fields of the 
WIND resource after it has been read in from 
the file. */ 


ae WINDRecord 


Rect boundsRect; 
INTEGER ргос10; 
Boolean visible; 
char filler 1; 
Boolean goAwayF lag; 
char filler2; 
LONGINT  refCon; 
947255 | title; 


); 
typedef struct WINDRecord WINDData; 
typedef struct WINDRecord *WINDPtr; 
typedef struct WINDRecord **WINDHandle; 


/* The WOEFHeader structure matches the 
structure of the (optional) header of а 
window definition procedure resource. */ 


a d WDEFRecord 


INTEGER branch; 
INTEGER flags; 
LONGINT type; 
INTEGER ID; 
INTEGER version; 


typedef struct WDEFRecord WDEFHeader; 
typedef struct WDEFRecord *WDEFPtr; 
typedef struct WDEFRecord **WDEFHandle; 


/* 
* GLOBALS 
*/ 
static WindowPeek toBeActivated, 
toBeDeact ivated, 
frontToolWindow, 
backToolWindow, 
frontDocWindow; 


static RgnHandle firstRgn, 
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SecondRgn; 
static SysEnvRec  theWorld; 


х TINITWINDOWS 


TIni tWindows¢ ) 
( 


OSErr err; 


frontToolWindow 
backToolWindow 

frontDocWindow 

toBeDeact ivated 
toBeAct ivated nil; 

firstRgn = NewRgnC); 

secondRgn = NewRgn(); 

err = SysEnvirons( curVersion, &theWorld ); 


x TGETNEWWINDOW 
*/ 


WindowPtr 
TGetNewWindow€ windowKind, windowID, 
wStorage, behind 2 
INTEGER windowKind; 
INTEGER windowID; 
Ptr wStorage; 
WindowPtr behind; 


Rect boundsRect; 
Str255 title; 

Boolean visible; 
INTEGER procID; 
Boolean goAwayF lag; 
LONG INT refCon; 
WindowPtr  theWindow; 
WINOHandle theWINDHandle; 
WINOPtr theWINDPtr; 


theWINOHandle - 

С WINOHandle )GetResource( 'WIND',windowID 2; 
if С theWINDHandle != nil ) 
( 


theWINDPtr = *theWINDHandle; 
boundsRect = theWINDPtr->boundsRect; 
visible = theWINDPtr->visible; 
procID - theWINDPtr-?procID; 
goAwayF lag = theWINDPtr-?goAwayF lag; 
refCon = theWINDPtr->refCon; 


if € theWINDPtr-> title. length == 8 ) 
title. length = 0; 
else 
BlockMoveC &C theWINDPtr->title ), &title, 
С Size OtheWINDPtr— title. length + 1 ); 
p2cstr( &title ); 


ReleaseResource(( Handle )theWINDHandle ); 
theWindow = 
NewWindowC wStorage, &boundsRect, &title, 
invisible, procID, behind, 
goAwayFlag, refCon 2; 
if С theWindow != nil ) 


(С WindowPeek )theWindow 2-?windowKind = 
windowKind; 
if С visible != false ) 
TShowWindowC theWindow 2; 
) 
else 
theWindow = nil; 
returnC theWindow ); 
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) 

/* 

х TNEWWINDOM 
*/ 


WindowPtr 
TNewWindowC windowKind, wStorage, boundsRect, 
title, visible, procID, behind, 
goAwayF lag, refCon ) 
INTEGER windowK ind; 


Ptr wStorage; 
Rect *boundsRect ; 
char *title; 
Boolean . visible; 


INTEGER ргос10; 
WindowPtr behind; 
Boolean goAwayF lag; 
LONGINT refCon; 


WindowPtr theWindow; 


theWindow = 
NewWindowC wStorage, boundsRect, title, 
invisible, procID, behind, 
goAwayF lag, refCon 2; 
if С theWindow != nil ) 


(С WindowPeek )theWindow )->»windowKind = 
windowKind; 
if € visible != false ) 
TShowWindowC theWindow 2; 


returnC theWindow 2; 


/* 
х TCLOSEWINDOY 
*/ 


void 
TCloseWindowC theWindow ) 
WindowPtr — theWindow; 


THideWindowC theWindow 2; 
CloseWindow( theWindow 2; 


if € theWindow == toBeDeactivated ) 
toBeDeactivated = nil; 


/* 
х TOISPOSEWINDOWN 
%/ 


void 
TDisposeWindowC theWindow 2 
WindowPtr — theWindow; 


THideWindowC theWindow 2; 
DisposeWindowC theWindow 2; 


if € theWindow == toBeDeactivated ) 
toBeDeactivated = nil; 


x 


* TSELECTWINDOW 
*/ 

void 

TSelectWindow( theWindow ) 
WindowPtr — theWindow; 
void BringForward(); 
WindowPeek  thePWindow, 
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theFrontWindow, 
NextVisWindow(), 
PrevVisWindow(C ); 
theWK ind, 

frontWK ind; 
toolsVisible, 

Br ingToolsForwardt(); 


INTEGER 


Boolean 


/* Initialize some variables. */ 


thePWindow = С WindowPeek )theWindow; 

theFrontWindow = С WindowPeek OFrontWindowC); 

theWK ind = TGetWKind(C theWindow ); 

frontWK ind = TGetWKindCC WindowPtr OtheFrontWindow 2; 


if € theWKind == toolKind ) 
( 
( С frontWKind == systemKind ) 


/* Window is а tool window, with а desk 
eccessory on top. */ 


SelectWindow€ theWindow ); 
(void BringToolsForward( thePWindow ); 
if С frontDocWindow != nil ) 


frontDocWindow->hilited = true; 

BringForward( frontDocWindow, 
backToo1Window, 
normalCalc ); 

toBeActivated = frontDocWindow; 


frontToolWindow = thePWindow; 


else 


/* Window is а tool window, and no desk 
accessory on top. */ 


( ( thePWindow != frontToolWindow ) 
if € thePWindow == backToolWindow 2 


backToolWindow = 
NextVisWindowC toolKind, thePWindow 2; 
if С backToolWindow == nil ) 
backToolWindow = PrevVisWindowC thePWindow 2; 


BringToFront(C theWindow ); 
frontToolWindow - thePWindow; 


) 
) 
ag if С theWKind == userKind ) 


( С frontWKind == systemKind ) 


/* Window is & document window Cor a 
modeless dialog window), with а desk 
eccessory on top. */ 


toolsVisible - 

BringToolsForwardCC WindowPeek 2inFront 2; 
if € toolsVisible == false ) 

SelectWindow( theWindow ); 
else 


thePWindow-^hilited = true; 
BringForwardC theWindow, 


backToolWindow, 
normalCalc 2; 


toBeActivated = frontDocWindow = thePWindow; 
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else 


/* Window is а document window Cor а 
modeless dialog window), and по desk 
accessory on top. */ 


e ( thePWindow != frontDocWindow 2 


if € frontToolWindow == nil ) 
SelectWindowC theWindow 2; 
else 


HiliteWindowCC WindowPtr frontDocWindow, 
false ); 
thePWindow->hilited = true; 
BringForward( thePWindow, 
backToolWindow, 
normalCalc 2; 


toBeDeactivated = frontDocWindow; 
toBeActivated = frontDocWindow = thePWindow; 


) 


) 
) 
) 
/* 
х THIDEWINDOW 
57 
void 
THideWindowC theWindow ) 
WindowPtr theWindow; 
WindowPeek  thePWindow, 
behindWindow; 
INTEGER theWK ind, 
thePosition, 
frontWKind, 
GetWPosition(); 
void HiliteTools(); 
if (CC WindowPeek OtheWindow )->visible 
Іш false 2 
thePWindow = С WindowPeek )theWindow; 
theWK ind = TGetWKindC theWindow 2; 
thePosition = GetWPositionC thePWindow, 


&frontWKind ); 


/* Hide the window, and update the desktop 
according to the window ° position. */ 


г ( theWKind == toolKind 2 
/* The window is а tool window. */ 
ee thePosition ) 


case alone: 

case beforeSystem: 
HideWindowC theWindow ); 
frontToolWindow = 
backToolWindow = nil; 
break; 


case beforeToo!: 
ShowHideC theWindow, false ); 
frontToolWindow = € WindowPeek )FrontWindow(); 
break; 


case behindFrontSystem: 
ShowHideC theWindow, false ); 
frontToolWindow = 
NextVisWindowC toolKind, 
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thePWindow 2; 
if С frontToolWindow == nil ) 
backToolWindow = nil; 
break; 


case beforeDocument: 
frontToolWindow = 
backToolWindow = nil; 
ShowHideC theWindow, false ); 
break; 


/* NOTE: no behindTools possible! */ 


case betweenTools: 
ShowHideC theWindow, false ); 
if € thePWindow == backToolWindow ) 
backToolWindow = PrevVisWindow( thePWindow 2; 
break; 


) 
"ius if € theWKind == userKind 2 


/* The window is a document window 
Cor a modeless dialog window). */ 


thePWindow- hilited = false; 
switch€ thePosition 2 


case alone: 

case beforeSystem: 
toBeDeactivated = thePWindow; 
frontDocWindow = nil; 


case betweenDocuments: 
HideWindowC theWindow ); 
break; 


case beforeDocument: 
HideWindowC theWindow 2; 
toBeDeactivated = thePWindow; 
toBeActivated = 
frontDocWindow = 
С WindowPeek )FrontWindow(); 
break; 


case behindFrontSystem: 
ShowHideC theWindow, false ); 
frontDocWindow - 
NextVisWindowC userKind, theWindow 2; 
break; 


case behindTools: 
frontDocWindow = 
NextVisWindowC userKind, theWindow); 
behindWindow = 
NextVisWindowC anyKind, theWindow 2; 
ShowHideC theWindow, false ); 
if € behindWindow == nil ) 
toBeDeactivated - thePWindow; 
else 


if С behindWindow != frontDocWindow) 
( С frontWKind == toolKind 2 


HiliteToolsC false ); 

SelectWindowCC WindowPtr ) 
behindWindow ); 

toBeDeactivated = thePWindow; 


if С frontDocWindow != nil 2 


BringForwardC frontDocWindow, 
backToo1lWindow, 
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normalCalc 2; 


else 
" С frontWKind == toolKind ) 


HiliteWindowC frontDocWindow, 
true ); 

toBeActivated = frontDocWindow; 

toBeDeactivated = thePWindow; 


break; 


else 
/* The window is а modal dialog window. */ 
switch( thePosition ) 


case alone: 

case beforeSystem: 

case beforeDialog: 
HideWindowC theWindow ); 
break; 


case beforeToo!: 

case beforeDocument: 
ShowHideC theWindow, false ); 
HiliteToolsC true ); 
if € frontDocWindow != nil ) 


toBeDeactivated - thePWindow; 

toBeActivated = frontDocWindow; 

HiliteWindowCC WindowPtr) 
frontDocWindow, true ); 


break; 


) 
) 


x TSHOWWINDOWM 
*/ 

void 

TShowWindowC theWindow ) 
WindowPtr X theWindow; 


WindowPeek  thePWindow, 


theFrontWindow, 
behind, 
PrevVisWindow( ); 
INTEGER theWK ind, 
frontWKind, 
thePosition, 
GetWPosition(); 
Boolean toolsExist, 
Br ingToolsForward(); 
void Br ingForward(), 
HiliteTools(); 
if ССС WindowPeek )theWindow )->visible 
í == false ) 

/* The window is still invisible. */ 
thePWindow = С WindowPeek )theWindow; 
theFrontWindow = С WindowPeek )FrontWindow(); 
theWK ind = TGetWKindC theWindow 2; 
thePosition = GetWPosition( thePWindow, &frontWKind 2); 
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e С theWKind == toolKind ) 

/* The window is а tool window. Assume 
it needs to appear highlighted 
(correct this later). */ 

thePWindow->hilited = true; 
SwitchC thePosition ) 


case beforeSystem: 
ShowWindowC theWindow 2; 


С void OBringToolsForward(CthePWindow); 


if € frontDocWindow != nil 2 


frontDocWindow->hilited = true; 

BringForward( frontDocWindow, 
backToolWindow, 
normalCalc 2); 

toBeActivated - frontDocWindow; 


frontToolWindow = thePWindow; 
break; 


case behindFrontSystem: 
thePWindow-»hilited = false; 


case alone: 
case beforeDocument : 
if С backToolWindow == nil ) 
backToolWindow = thePWindow; 


case beforeTool : 
ShowHideC theWindow, true ); 
frontToolWindow = thePWindow; 
break; 


case behindTools: 
backToolWindow = thePWindow; 


case betweenTools: 
if € frontWKind == systemKind ) 
thePWindow- hilited = false; 
ShowHideC theWindow, true 2; 
break; 


case behindSystem: 
SendBehind( theWindow, 
C WindowPtr )backToolWindow ); 
if С frontWKind == systemKind ) 
thePWindow->hilited = true; 
ShowHideC theWindow, true ); 
backToolWindow = thePWindow; 
break; 


case betweenDocuments: 
if С backToolWindow != nil ) 
behind = backToolWindow; 
else 


behind = 
PrevVisWindowC frontDocWindow ); 
frontToolWindow = thePWindow; 


) 

if С behind == nil ) 
BringToFront( theWindow ); 

else 


( 
SendBehindC theWindow, behind 2; 
if С frontWKind == systemKind 2 
thePWindow->»hilited = false; 


) 
ShowHideC theWindow, true 2; 
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backToolWindow = thePWindow; 
break; 


rias if С theWKind == userKind ) 


/* The window is а document window. */ 


SwitchC thePosition ) 


case beforeSystem: 
toolsExist = BringToolsForward( 
С WindowPeek )іпЕгопі 2; 
if € toolsExist != false ) 
thePWindow- hilited = true; 


case alone: 
ShowWindow( theWindow ); 
toBeActivated = frontDocWindow = thePWindow; 
break; 


case beforeToo!: 
if € frontDocWindow іс nil ) 


HiliteWindowCC WindowPtr ) 
frontDocWindow, false ); 
toBeDeactivated = frontDocWindow; 


SendBehindC theWindow, 

backToolWindow 2; 
thePWindow->hilited = true; 
ShowHideC theWindow, true ); 
toBeActivated = frontDocWindow = thePWindow; 
break; 


case beforeDocument: 


/* The three steps HiliteWindow, 
HiliteWindow and ShowHide could 
be replaced with one call to 
ShowWindow, but this gives а 
better visual effect. (Try the 
difference.) */ 


HiliteWindowC frontDocWindow, false ); 
HiliteWindow€ theWindow, true ); 
ShowHideC theWindow, true 2; 


toBeDeactivated = frontDocWindow; 
toBeActivated = frontDocWindow = thePWindow; 
break; 


case behindFrontSystem: 
if С backToolWindow != nil ) 
SendBehindC theWindow, 
С WindowPtr backToolWindow 2; 
ShowHideC theWindow, true ); 
frontDocWindow = thePWindow; 
break; 


case betweenTools: 
SendBehind( theWindow, 
С WindowPtr ObackToolWindow 2; 


case behindTools: 
( ( frontWKind == toolKind 2 


thePWindowhilited = true; 
toBeActivated = thePWindow; 
if € frontDocWindow != nil ) 


HiliteWindowCC WindowPtr ) 
frontDocWindow, false ); 
toBeDeactivated - frontDocWindow; 
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) 

ShowHideC theWindow, true ); 
frontDocWindow = thePWindow; 
break; 


case behindSystem: 
SendBehind( theWindow, 
€ WindowPtr ObackToolWindow 2; 
( ( frontWKind == toolKind 2 


thePWindow->hilited = true; 
toBeActivated - thePWindow; 


returnCC WindowPtr OfrontDocWindow 2; 
break; 


case anyKind: 
returnC theWindow ); 
break; 


) 
ShowHideC theWindow, true ); 


frontDocW indow 
break; 


- thePWindow; 


case betweenDocuments: 
ShowHideC theWindow, true ); 
break; 
) 
) 


else 
/* The window is a modal dialog window.*/ 
switchC thePosition ) 


case alone: 

case beforeSystem: 

case beforeDialog: 
ShowWindowC theWindow 2; 
break; 


case beforeTool: 

case beforeDocument : 
HiliteToolsC false 2; 
if С frontDocWindow != nil ) 


toBeDeactivated - frontDocWindow; 
HiliteWindowCC WindowPtr 2 
frontDocWindow, false ); 


) 
ShowHideC theWindow, true ); 


break; 
) 
) 

) 
) 
/* 

Ж TFRONTWINDOM 
*/ 
WindowPtr 


TFrontWindowC wantedKind 2 
INTEGER wantedK ind; 
( 
WindowPtr — theWindow; 
INTEGER theWK ind; 


theWindow = FrontWindow(); 
theWKind = TGetWKindC theWindow ); 


if С theWKind == systemKind || 
theWKind == dialogKind 2 
returnC theWindow ); 
else 
switch С wantedKind ) 
( 


case toolKind: 
returnCC WindowPtr OfrontToolWindow 2; 
break; 


case userKind: 
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/* 
ж TDRAGWINDOWM 
*/ 
void 
TDragWindowC theWindow, theEvent, boundsRect ) 
WindowPtr — theWindow; 
EventRecord *theEvent; 
Rect *boundsRect ; 
GrafPtr savePort, 
wPort; 
Rect limitRect, 
slopRect; 


RgnHandie mdesktopRgn; 
LONGINT result; 
INTEGER hDrag, 
vDrag; 
Point thePoint; 


i] (С theEvent->modifiers & cmdKeu ) == false ) 


TSelectWindowC theWindow ); 
if € StillDown() == false ) 
return; 


GetPort ( &sevePort 2; 
GetWMgrPort( &wPort 2; 
SetPort ( wPort ); 


if € theWorld.machineType == envMac || 
theWorld.machineTgpe == envXL ) 
desktopRgn = GrayRgn; 
else 
desktopRgn = GetGrayRgn(); 


GetClip € firstRgn 2; 
SetClip € desktopRgn ); 
ClipAboveCC WindowPeek OtheWindow 2; 


CopyRgnCCC WindowPeek )theWindow )-»strucRgn, 
secondRgn 2; 
SetPt С &thePoint, theEvent->where.h, 
theEvent->where.v ); 
GlobalToLocal( &thePoint 2; 
result = ОгадбгауКап( secondRgn, &thePoint, 
boundsRect, boundsRect, 
noConstraint, С ProcPtr Эп11 ); 


SetClipC firstRgn 2; 


vDrag = HiWord( result 2; 
hDrag = LoWordC result ); 
( С !€ vDrag == noDrag 8% hDrag == noDrag 22 


SetPortC theWindow 2); 

SetPt С &thePoint, 
theWindow->portRect. left, 
theWindow->portRect.top ); 

LocalToGlobalC &thePoint ); 

MoveWindowC theWindow, thePoint.h + hDrag, 

thePoint.v + vDrag, false ); 


SetPort( savePort 2; 
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SetEmptyRgn( f irstRgn ); 
SetEmptyRgn( secondRgn 2); 


/* 
ж TGETNEXTEVENT 
*/ 


Воо1еап 

TGetNextEvent( eventMask, theEvent ) 
INTEGER — eventMask; 
EventRecord *theEvent; 


Boolean result, 
WindowExists(); 

INTEGER — theWKind; 

void X HiliteToolsC); 


if С EventAvailC eventMask, theEvent ) 
l= false && 
theEvent->what == activateEvt ) 


result = GetNextEventC eventMask, theEvent ); 
theWKind = TGetWKindCC WindowPtr )theEvent->message ); 


if СС theEvent->modifiers & activeFlag ) 
== false ) 


if € theEvent-»message != С LONGINT )toBeDeactivated 2 


if С toBeDeactivated != nil ) 
theEvent->message = (С LONGINT )toBeDeactivated; 
else 


userKind || 


if С theWKind == 
d == toolKind ) 


theWK in 


if € theWKind == toolKind ) 
HiliteToolsC false ); 
| С frontDocWindow |= nil ) 


HiliteWindowCCWindowPtrOfrontDocWindow, false ); 
theEvent-?message = С LONGINT )frontDocWindow; 


else 
result = TGetNextEventC eventMask, theEvent ); 


) 
toBeDeactivated = nil; 
else 


if С theEvent-»message 
Із € LONGINT )toBeActivated ) 


if € toBeActivated != nil ) 
theEvent->message = 
С LONGINT )toBeActivated; 
else 


if С theWKind == userKind || 
theWKind == toolKind ) 


if € theWKind == toolKind ) 
HiliteToolsC true ); 
if € frontDocWindow != nil ) 


HiliteWindowCC WindowPtr ) 
frontDocWindow, true 2; 
theEvent-?message = 
€ LONGINT )frontDocWindow; 


else 
result = TGetNextEvent( eventMask, theEvent ); 
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) 
) 
toBeActivated = nil; 
) 
else 
if € toBeDeactivated != nil kk 
( eventMask & activMask ) != false ) 
if С WindowExists( toBeDeactivated ) 
( != false ) 
theEvent-?what = activateEvt; 
theEvent->message = ( LONGINT )toBeDeactivated; 
theEvent-»modif iers = deactivFlag; 
toBeDeactivated = nil; 
result = true; 
else 
toBeDeactivated = nil; 
result = TGetNextEvent( eventMask, theEvent ); 

) 

else if С toBeActivated != nil && 

( eventMask & activMask) != false ) 
theEvent-? what - activateEvt; 
theEvent-?»message = (С LONGINT OtoBeAct ivated; 
theEvent-?modif iers = activeFlag; 
toBeActivated = nil; 

) result = true; 

else 
result = GetNextEvent( eventMask,theEvent); 

) 


return( result ); 


* 


* WINDOWEXISTS 
х/ 


Boolean 
WindowExistsC thePWindow ) 
WindowPeek  thePWindow; 


WindowPeek  loopWindow; 
Boolean done; 


for С done = false, 
loopWindow = WindowList; 
done == false && loopWindow != nil; 
loopWindow = loopWindow-?nextWindow ) 


if С loopWindow == thePWindow ) 
done = true; 


return( done ); 


) 


/* 
* GETWPOSITION 
*/ 


static INTEGER 

GetWPositionC thePWindow, frontWKind ) 
WindowPeek  thePWindow; 
INTEGER *frontWK ind; 
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WindowPeek theFrontWindow, 
newFrontWindow, 
loopWindow, 
NextVisWindow( ); 

Boolean done; 

INTEGER result, 
loopWK ind; 


theFrontWindow = С WindowPeek )FrontWindow(); 


if € thePWindow visible != false && 
theFrontWindow == thePWindow ) 
newFrontWindow = NextVisWindowC anyKind, theFrontWindow 2; 
else 
newFrontWindow = theFrontWindow; 


if С newFrontWindow == nil ) 
return( alone ); 
*frontWKind = TGetWKindCC WindowPtr dnewFrontWindow ); 


if € thePWindow visible != false && 
theFrontWindow -- thePWindow || 
theFrontWindow == NextVisWindowC anuKind, thePWindow 22 


/* Our window is visible and the frontmost, 
or it’s invisible and lying in front of 
the frontmost visible window. */ 


if € *frontWKind == systemKind ) 
result = beforeSystem; 

else if С *frontWKind == dialogKind ) 
result = beforeDialog; 

else if С *frontWKind == toolKind ) 
result = beforeToo!; 

else 
result = beforeDocument; 


else 


if CthePWindow->visible |= false ) 
thePWindow = PrevVisWindowC thePWindow ); 


for ( done = false, 
loopWindow = theFrontWindow; 
done == false; 
loopWindow = loopWindow-?nextWindow ) 


loopWKind = 
TGetWKindCC WindowPtr )loopWindow ); 
if € loopWindow == theFrontWindow  && 
loopWKind -- systemK ind ) 
result = behindFrontSystem; 
else if С loopWindow == frontToolWindow && 
backToolWindow != frontToolWindow ) 
result = betweenTools; 
else if С loopWindow == backToolWindow ) 
result - behindTools; 
else if С loopWKind == systemK ind %% 
loopWindow-— visible != false && 
result == behindTools 2 
result = behindSystem; 
else if С loopWindow == frontDocWindow ) 
result = betweenDocuments; 


if € loopWindow == thePWindow ) 
done = true; 


return( result ); 


) 

/* 

* TGETWKIND 
х/ 
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INTEGER 
TGetWKindC theWindow ) 


WindowPtr — theWindow; 


INTEGER theWK ind, 
varCode, 
windowID; 

WDEFHandle defProc; 


г С theWindow != nil ) 


theWK ind = 
(С WindowPeek )theWindow 2-»windowKind; 


if € theWKind <- systemKind ) 
theWKind = systemKind; 

else if С theWKind == dialogKind ) 

( 


defProc = 
€ WwDEFHandle ) 
CCWindowPeek )theWindow )->windowDefProc; 


if С theWorld.machineType == envMac || 
theWorld.machineType == envXL ) 


varCode = ( LONGINT )defProc >> 24 && 0x0000000F ; 


else 
varCode = GetWVariant( theWindow ); 


if С defProc != nil  && 
*defProc |= nil && 
С *defProc )->type == ‘WDEF’ ) 


windowID = 
С *defProc 2-210 * 16 + varCode; 
else 
windowID = dBoxProc; 
if С windowID == documentProc || 
windowID == noGrowDocProc || 
windowID == zoomDocProc 2 


theWKind = userKind; 


else if С theWKind == toolKind ) 
/* nothing */ ; 

else if С theWKind >= userKind ) 
theWKind = userKind; 


) 
return( theWKind ); 


/* 
х BRINGTOOLSFORWARD 
*/ 


static Boolean 
BringToolsForward( thePWindow ) 
WindowPeek thePWindow; 


WindowPeek NextVisWindow(), 
toolWindow, 
loopWindow; 

void Br ingForwardC); 


Ü ( thePWindow == С WindowPeek JinFront ) 


toolWindow - NextVisWindowC toolKind, 
С WindowPeek JFrontWindowC) ); 


if € toolWindow != nil ) 
loopWindow = toolWindow->nextWindow; 
SelectWindowCC WindowPtr )toolWindow 2; 
frontToolWindow = backToolWindow = toolWindow; 


else 
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) 


return( false ); /* 
) * PREVVISWINDOW 
) */ 
else 
static WindowPeek 
loopWindow = thePWindow- nextWindow; PrevVisWindowC thePWindow 2 
backToolWindow = thePWindow; WindowPeek  thePWindow; 
WindowPeek  loopWindow, 
SetEnmptyRgnC secondRgn 2); prevWindow, 
thePWindow = nil; theFrontWindow, 
NextVisWindow(); 
while € loopWindow != nil ) Boolean done; 
if С loopWindow-?windowKind == toolKind 6 theFrontWindow = € WindowPeek )FrontWindow(); 
loopWindow-? visible l= false ) 
if С thePWindow == theFrontWindow || 
toolWindow = loopWindow; theFrontWindow == 
toolWindow->hilited = true; NextVisWindow€ anyKind, thePWindow 22 
BringForward( toolWindow, backToolWindow, return(( WindowPeek )п11 2; 
postponeCalc ); 
UnionRgnC secondRgn, toolWindow-?strucRgn, prevWindow = theFrontWindow; 
secondRgn ); loopWindow = prevWindow->nextW indow; 
backToolWindow = toolWindow; done = false; 
if С thePWindow == nil ) 
thePWindow = toolWindow; while ( done == false ) 
loopWindow = loopWindow-?nextWindow; if € loopWindow == thePWindow ) 
done - true; 
else 
CalcVisBehindC thePWindow, secondRgn 2; if С loopWindow- visible != false ) 
SetEmptyuRgnC secondRgn 2; prevWindow = loopWindow; 
loopWindow = loopWindow-?nextWindow; 
return( true 2; 
returnC prevWindow ); 
/* End of BringToolsForwerd */ 
/% /* 
% NEXTVISWINDOW х BRINGFORWARD 
*/ 2] 
stetic void 
static WindowPeek BringForwardC thePWindow, behindWindow, 
NextVisWindowC wantedKind, thePWindow 2 waitWithCalc ) 
INTEGER wentedK ind; WindowPeek  thePWindow; 
WindowPeek  thePWindow; WindowPeek behindWindow; 
Boolean waitWithCalc; 
WindowPeek  loopWindow, 
wentedWindow; CopyRgn € thePWindow- strucRgn, firstRgn 2; 
OffsetRgnC thePWindow- port .visRgn, 
if С thePWindow == С WindowPeek DinFront ) - thePWindow-?port.portBits.bounds. left, 
( - thePWindow->port.portBits.bounds.top ); 
thePWindow = С WindowPeek DFrontWindow( ); DiffRgn С firstRgn, thePWindow->port.visRgn, 
if € thePWindow == nil ) firstRgn ); 
return( thePWindow ); OffsetRgnC thePWindow- port .visRgn, 
else if ( wantedKind == anyKind || thePWindow->port.portBits.bounds. left, 
wantedKind ==TGetWKind(( WindowPtr)thePWindow 22 thePWindow->port .portBits.bounds.top ); 
returnC thePWindow 2; 
SendBehindCC WindowPtr )thePWindow, 
С WindowPtr ObehindWindow 2; 
for С wantedWindow = nil, PaintOneC thePWindow, firstRgn 2; 
loopWindow = thePWindow-?nextWindow; if € waitWithCalc == false ) 
wantedWindow == nil && CalcVisBehindC thePWindow, 
loopWindow != nil; thePWindow-?strucRgn 2; 
loopWindow = loopWindow- nextWindow ) SetEmptyRgnC firstRgn 2; 
if С loopWindow- visible != false ) /* 
if € wantedKind == anuKind || * HILITETOOLS 
wantedKind == */ 
TGetWKindCC WindowPtr )loopWindow 22 
wantedWindow = loopWindow; stetic void 
HiliteToolsC hilite ) 
Boolean hilite; 


returnC wantedWindow 2; 
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WindowPeek  loopWindow; 
Boolean done; 


if € frontToolWindow != nil ) 


for С done - false, 
loopWindow = frontToolWindow; 
done == false %%  loopWindow != nil; 
loopWindow = loopWindow->nextWindow ) 


if С TGetWKindCC WindowPtr )loopWindow ) 
== toolKind && 
loopWindow visible != false ) 


HiliteWindowCC WindowPtr )loopWindow, hilite 2; 
if С loopWindow == backToolWindow ) 
done = true; 


) 
) 
) 


Listing: TWindow.h 


— 
* 


TWindows.h 


Include file for usage with the TWindow 
Manager, an extended window manager that 
supports tool windows; these are windows 
that always float on top, for palettes and 
tools. 


Written in MPW C 2.0 


Copyright Thomas Fruin 1988 
All rights reserved. 


3 3 3 MH HH HM 34 ж м HM HM м 


5. 


/* 
* TYPES 
T, 
/* Define the standard toolbox types INTEGER 
and LONGINT in terms of the equivalents for 
the MPW C compiler. */ 


"def ine INTEGER short 
#def ine LONGINT long 


/* Constants for the kindes of windows */ 


[> dialogKind 2. %7 
/* userK ind 8 */ 
"define systemKind =] 


gef ine toolKind 30000 
#def ine anyKind 30001 
8define inFront CCWindowPtr)-1) 


/* Callable functions in the TWindow Manager */ 


void TInitWindows(); 
WindowPtr TNewW indow( ); 
WindowPtr TGetNewWindow( ); 


void TCloseWindowC); 
void TDisposeW indow( ); 
void TSelectWindow(); 
void THideW indow( ); 
void TShowWindowC?; 
WindowPtr TFrontwindow( ); 
void TDragwW indow( ); 
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Boolean TGetNextEvent(); 
INTEGER TGetWKindC); 


Listing: make TWindowTester 


Makefile for TWindowTester and TWindows 


TWindowTester is a simple program to demon- 
strate the usage of tool windows by using 
routines from TWindows, а complete manager 
for handling these windows that always float 
on top, ususally used for palettes and tools. 


Copyright Thomas Fruin 1988 
А11 rights reserved 


1$ tt tt + + T 3$ - 3$ 3:3 58 oH 


Libs = *(CLibraries)"CInterface.o д 
* (CLibraries) "CRuntime.o д 
* (CLibraries)"glueenvirons.a.o д 
* (CLibraries)"StdCLib.o 


TWindowTester ff TWindowTester.c.o TWindows.c.o 
Link TWindowTester.c.o 9 
TWindows.c.o 
(Libs) 
-0 TWindowTester 
-t ‘APPL’ 
-с ‘TWIN’ 


© б> бх C» 


TWindowTester ff TWindowTester.r 
rez -о TWindowTester 9 


Types.r 9 
TWindowTester.r 9 
-а 


TWindowTester.c.o f TWindowTester.c TWindows.h 
C TWindowTester.c 


TWindows.c.o Í Twindows.c 
С TWindows.c -d _ ALLNU__ 


Listing: TWindowTester.c 
/* 

* TWindowTester 

x 


*C source of a program to demo usage of tool windows by 
*using routines from the TWindow Manager. Tool windows are 
*windows that always float on top, typically for palettes and 
*tools. 


* Thomas Fruin 1988 

x 

Ж fruin@éhlerul5.BITNET University of Leiden 

*  thomas8uvebick.UUCP University of Amsterdam 
х dibs8well.UUCP 

Ж  hol066.AppleL ink 

* 2:508/15.FidoNet The Netherlands 

x 


*TWindowlester is based on MiniEdit - Mini text 

* editor, converted from 

*the listing in Macintosh Revealed, vol II. As little as 
* possible was 

*modified in the original program, although most of the 
*functionality is no longer there. 

*/ 


®include «Турев.һ» 
8include «QuickDraw.h? 
*include «Fonts.h» 
include «Windows.h? 
include <Events.h> 

8 include «TextEdit.h» 
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include 
include 
tt include 
include 
tinclude 
t include 
$t include 


ttinclude 


«Controls.h? 


«Dialogs.h? 


«Menus .h? 


«Memory.h? 
«0SUtils.h? 


«ToolUtils.h»? 


«Desk.h? 


«TWindows.h? 


def ine MenuBarHeight 20 
define TitleBarHeight 18 
def ine ScreenMargin 4 


def ine MinWidth 80 
"define MinHeight 80 
"define SBarWidth 16 


define AppleID 
def ine AboutItem 


define FileID 
def ine New! tem 
"define NewToolltem 2 
tdef ine Closeltem 
gef ine QuitItem 


— № 


"def ine EditID 
def ine UndoItem 
def ine CutItem 
"def ine Сору tem 
#def ine PasteItem 
define CleerItem 


~ CO! We C) сл сә 


define WindowsID 4 
"define ToolsID 5 


define About ID 128 
8def ine windowID 1000 
def ine scrollID 1000 
"define {00110 1001 


"define okButton 1 
#def ine aboutBold 8 


def ine wHOffset 20 
define wVOffset 20 
"define tHOffset 40 
define tVOffset 40 


#def ine undoCmd 0 
def ine cutCmd 2 
def ine copyCmd 3 
"def ine pasteCmd 4 
def ine clearCmd 5 


/* z-ordered list of windows (nearest first) */ 


C*CWindowPeek %20х906 2 
((РгосР4г 202 


def ine windowList 
"define nilproc 


struct WindowData 
ControlHandle scBar; 


typedef struct WindowDeta WindowData; 
typedef struct WindowData *WDPtr; 
typedef struct WindowData **WDHandle; 


MenuHandle ` AppleMenu, 
FileMenu, 
EditMenu, 
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WindowsMenu, 
ToolsMenu; 
INTEGER toolCount, 
windowCount, 
lastToolsItem, 
lastWindows! tem; 
Boolean Finished, 
ErrorF lag; 
maint) 
Initialize); 
do 


InitializeC) 


) 


ее 


DrawMenuBar(); 
lestToolsItem = 
) lestWindowsItem = 0; 
е 
EventRecordtheEvent; 


if € FrontWindow() == nil ) 
DisableItem( FileMenu, CloseItem ); 

SystemTask(); 

DoEvent(); 


) 
while C !Finished ); 


INTEGER 


theMask; 


InitGraf( &qd.thePort ); 
InitFonts(); 
Ini tWindows(); 
InitMenus( ); 


TEInitO; 


InitDialogsC nilproc 2; 


TInitWindows(); 


theMask = everyEvent - keyUpMask; 
SetEventMask( theMask ); 
FlushEvents( everyEvent, 0 ); 


SetUpMenus( ); 
InitCursor(); 


AppleMenu = GetMenuC AppleID 2; 
AddResMenuC AppleMenu, ‘DRVR’ ); 
InsertMenuC AppleMenu, Ø ); 


FileMenu = GetMenuC FileID 2; 
InsertMenuC FileMenu, 0 ); 


EditMenu = GetMenuC EditID ); 
InsertMenuC EditMenu, 0 ); 


WindowsMenu = GetMenuC WindowsID 2; 
InsertMenuC WindowsMenu, 0 2; 


ToolsMenu = GetMenuC ToolsID ); 
InsertMenuC ToolsMenu, 0 2; 
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ErrorFlag = false; DoMenuChoiceC menuChoice ); 


if С TGetNextEvent€ everyEvent, &theEvent )) 
( DoMenuChoiceC menuChoice ) 


е ( theEvent.what 2 LONG INT menuChoice; 
case mouseDown: INTEGER theMenu, 
DoMouseDown( &theEvent 2; theItem; 
break; 


if С menuChoice ) 
case keyDown: 
case autoKeu: theMenu = HiWordC menuChoice 2); 
DoKeyStrokeC &theEvent 2; theItem = LoWordC menuChoice ); 
break; 
Switch CtheMenu) 
cese updateEvt: ( 


DoUpdate( &theEvent ); case AppleID: 
break; DoAppleChoiceC theItem 2; 
break; 
case activateEvt: 
DoActivateC &theEvent ); case FileID: 
break; DoFileChoice( theltem ); 
break; 
default: 
break; case EditID: 
DoEditChoice( theltem ); 
) ) break; 
case WindowsID: 
DoMouseDown( theEvent 2 DoWindowsChoiceC WindowsMenu, theItem ); 
EventRecord*theEvent; break; 
WindowPtr  whichWindow; cese ToolsID: 
INTEGER thePart; DoWindowsChoiceC ToolsMenu, theItem ); 


break; 
thePart = FindWindowC &theEvent->where, &whichWindow ); 


HiliteMenuC 0 ); 
"d C thePart 2 


) 
case inDesk: 
break; DoAppleChoiceC theItem ) 
INTEGER theItem; 
сазе inMenuBar: ( 
DoMenuClickC theEvent 2); char accName[255]; 
break; INTEGER accNumber ; 
cese inSysWindow: switch С theItem ) 
SystemClickC theEvent, whichWindow 2; 
break; case About! tem: 
DoAbout(); 
case inContent: break; 
DoContent( theEvent, whichWindow ); 
break; default: 
EnableItemC FileMenu, CloseItem ); 
case inDrag: 
DoDreg( theEvent, whichWindow ); EnableItem( EditMenu, UndoItem ); 
break; EnableItemC EditMenu, CutItem ); 
EnableItemC EditMenu, CopyItem ); 
case inGrow: EnebleItemC EditMenu, PesteItem ); 
DoGrowC theEvent, whichWindow 2; EnableItemC EditMenu, ClearItem ); 
break; 
GetItemC AppleMenu, theItem, accName ); 
case inGoAway: accNumber = OpenDeskAcc( accName ); 
DoGoAwayC theEvent, whichWindow ); break; 
break; ) 
) ) 
) 
DoAbout() 
DoMenuClick( theEvent ) ( 
EventRecord*theEvent; EventRecordtheEvent; 
DialogPtr aboutDialog; 
LONGINT menuChoice; INTEGER іһе tem; 


void SetBold(); 
menuChoice = MenuSelect( &theEvent->where ); 
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aboutDialog = GetNewDialog( AboutID, nil, inFront 2; ); 
SetBoldC aboutDialog, aboutBold 2; 
TShowindowC aboutDialog ); OffsetWindowC toolWindow, tHOffset, tVOffset, &toolCount ); 
TShowWindow( toolWindow 2; 
if С TGetNextEventC activMask, &theEvent 2) 
DoActivateC &theEvent ); SetPortC toolWindow 2; 


if € TGetNextEventC activMask, &theEvent 22 EnableItemC FileMenu, CloseItem 2; 
DoActivateC &theEvent 2; 


GetWTitleC toolWindow, title 2; 
ModalDialog( nilproc, &theItem 2; InsMenuItemC ToolsMenu, title, lastToolsItem++ ); 
CheckItem ( ToolsMenu, lestToolsItem, true 2; 


THideWindow С aboutDialog ); ) 
DisposDialogC eboutDialog 2; 
) OffsetWindowC whichWindow, hOffset, vOffset, count ) 
WindowPtr  whichWindow; 
DoFileChoiceC theItem ) INTEGER hOffset, 
INTEGER theItem; vOffset, 
*count; 
Switch CtheItem) ( 
( INTEGER windowWidth, 
case NewItem: windowHeight, 
DoNew( ); hExtre, 
break; vExtra, 
hMax, 
case NewToolItem: vMax, 
DoNewToo1C); windowLeft, 
break; windowTop; 
Rect  pRect; 
cese CloseItem: char title [ 255 |, 
DoClose(); number[ З J; 
break; 


pRect = whichWindow-?portRect; 
case QuitItem: 


0004140); windowWidth = pRect.right - pRect.left; 
break; windowHeight = pRect.bottom - pRect.top; 
| ) windowHeight += TitleBarHeight; 
hExtra = qd.screenBits.bounds.right - windowWidth; 
DoNewC ) vExtra = qd.screenBits.bounds.bottom - С windowHeight + 
( MenuBarHeight ); 
WindowPtr theWindow; 
WDHandle theData; hMax = С hExtra / hOffset 2 + 1; 
char  title( 255 1; vMax = С vExtre / vOffset ) + 1; 
theWindow = TGetNewWindowCuserKind, windowID, nil, infront 2; ***count; 
OffsetWindowC theWindow, wHOffset, wVOffset, &windowCount 2; windowLeft = С *count Я hMax ) * hOffset; 
TShowWindow С theWindow ); windowTop = С *count $ vMax ) * vOffset; 
windowTop = windowTop + TitleBarHeight + MenuBarHeight; 


SetPortC theWindow 2; 


MoveWindowC whichWindow, windowLeft, windowTop, false ); 
theDate = € WOHendle )NewHandle(( Size ӘвігеоҒ( WindowData 


22; GetWTitleC whichWindow, title ); 
SetWRefConC theWindow, С LONGINT OtheData 2; NumToStringCC LONGINT )*count, number 2; 
HLockC theDeta 2; SetWTitleC whichWindow, strcat( title, number 22; 
С *theDate )-›ѕсВаг = GetNewControlC scrollID, theWindow 2); 
DoClose() 
HUnlock( theData ); ( 


WindowPtr  whichWindow; 


EnaebleItemC FileMenu, CloseItem 2; INTEGER theWK ind; 

GetWTitleC theWindow, title 2; whichWindow = TFrontWindowC userKind 2; 

InsMenuItemC WindowsMenu, title, lestWindowsItem** ); 

CheckItem (С WindowsMenu, lastWindowsItem, true ); if С whichWindow != nil ) 

theWKind = TGetWKind( whichWindow 2; 

DoNewToo1C) oo theWKind 2 
( 

WindowPtr  toolWindow; case userKind: 

cher titlel 255 1; CloseDocWindowC whichWindow 2; 


break; 
toolWindow » TGetNewWindowC toolKind, toolID, nil, inFront 
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case systemK ind: 
CloseSysWindow С whichWindow ); 
break; 


) 


else 
whichWindow = TFrontWindowC toolKind ); 


if € whichWindow != nil ) 
CloseToolWindowC whichWindow ); 


) 


CloseDocWindowC whichWindow ) 
WindowPtr  whichWindow; 


WDHandle theData; 
INTEGER Itemof C); 
EventRecordtheEvent; 


lastWindowsItem-; 

DelMenuItemC WindowsMenu, ItemOfC whichWindow, WindowsMenu 

22; 
theData = С WDHandle )GetWRefCon( whichWindow ); 
THideWindowC whichWindow ); 


if С TGetNextEventC activMask, &theEvent 22 
DoActivateC &theEvent ); 


if ( TGetNextEventC activMask, &theEvent )) 
DoActivate( &theEvent ); 


if € theData != nil ) 


DisposHandleC theData ); 
TDisposeWindowC whichWindow 2); 


CloseToolWindowC whichWindow ) 
WindowPtr whichWindow; 
INTEGER Itemof C5; 
lastToolsItem-; 
DelMenuItemC ToolsMenu, ItemOf(C whichWindow, ToolsMenu 2); 


TDisposeWindowC whichWindow 2; 


) 


CloseSysWindowC whichWindow ) 
WindowPtr whichWindow; 


INTEGER accNumber ; 
accNumber = (C WindowPeek OwhichWindow )-»windowKind; 
CloseDeskAcc( accNumber ); 
ент) 
Finished = true; 
DoEditChoiceC theItem ) 
INTEGER theItem; 
үле C theItem ) 
case UndoItem: 
if С !SystemEdit€ undoCmd )) 


DoUndo( ); 
break; 
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case CutItem: 
if € !SystemEditC cutCmd )) 
DoCutC); 
break; 


case CopyItem: 
if С !SystemEdit( copyCmd )) 
DoCopy(); 
break; 
case Pastel tem: 
if € !SystemEditC pasteCmd 2) 
DoPasteC); 
break; 


case ClearItem: 
if С !SystemEditCclearCmd )) 
DoClear(); 
break; 
} 
(ala 


SysBeep( 1); 


DoCutC) 


ЗузВеер( 1); 


о 


SysBeep( 1); 


DoPasteC) 


SysBeep( 1); 


тайын 
SysBeep( 1); 
DoWindowsChoiceC theMenu, theItem ) 
MenuHandle theMenu; 
INTEGER theI tem; 
INTEGER theMark; 
WindowPtr whichWindow, 
WindowOf C); 


whichWindow = WindowOfC theMenu, theItem ); 
GetI temMark( theMenu, theItem, &theMark ); 


if С theMark == noMark ) 


CheckItemC theMenu, theItem, true ); 
TShowWindowC whichWindow 2; 


else 


CheckItemC theMenu, theItem, false ); 
THideWindowC whichWindow 2; 


) 
DoContent( theEvent, whichWindow ) 


EventRecord*theEvent ; 
WindowPtr  whichWindow; 
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INTEGER theWKind; 
theWKind = TGetWKindC whichWindow 2; 
if € theWKind -- userKind ) 


if С whichWindow != TFrontWindowC userKind )) 
TSelectWindowC whichWindow ); 


else if ( theWKind == toolKind ) 


if € whichWindow != TFrontWindowC toolKind 22 
TSelectWindowC whichWindow ); 


/* Only if the window has no title bar */ 
DoDrag( theEvent, whichWindow 2; 
) 


DoDrag( theEvent, whichWindow) 
EventRecord*theEvent ; 
WindowPtr whichWindow; 


Rect limitRect; 

SetRect( &limitRect, 0, MenuBarHeight, 
qd.screenBits.bounds.right, 
qd.screenBits.bounds.bottom ); 

InsetRect( &limitRect, ScreenMargin, ScreenMargin 2; 

TDragWindow( whichWindow, theEvent, &limitRect ); 


DoGrowC theEvent, whichWindow ) 
EventRecord*theEvent; 
WindowPtr  whichWindow; 


Rect  sizeRect; 


LONGINT newSize; 

INTEGER newWidth, 
newHeight; 

GrafPtr savePort; 


if C whichWindow |= TFrontWindowC userKind 2) 
TSelectWindowC whichWindow 2; 
else 


SetRect( &sizeRect, MinWidth, MinHeight, 
qd.screenBits.bounds.right, 


qd.screenBits.bounds.bottom - MenuBarHeight 2; 


newSize = GrowWindowC whichWindow, &theEvent->where, 
&sizeRect 2; 


if ( newSize ) 


GetPort( &savePort 2; 

SetPortC whichWindow 2; 

EreseRectC &whichWindow-?portRect 2; 

newWidth = LoWord( newSize ); 

newHeight = HiWord( newSize 2; 

SizeWindowC whichWindow, newWidth, newHeight, true ); 
InvalRect( &whichWindow- portRect 2; 

Ғіхӛсго11Ваг( whichWindow 2; 

SetPort( savePort 2; 


) 
) 
) 
FixScrollBarC whichWindow 2 
WindowPtr whichWindow; 
( 
WDHandle ^X theData; 
ControlHandle theScro1 1Bar ; 
Rect pRect; 
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theData = С WDHandle OGetWRefConC whichWindow 2; 
( С theData != nil ) 


theScrollBar = € *theData 2-25сВаг; 
HideControlC theScrollBar 2; 
pRect = whichWindow- portRect; 


MoveControlC theScrollBar, pRect.right - С SBarWidth - 1 


2, “12; 


) 


SizeControlC theScrollBar, SBarWidth, ( pRect.bottom + 1) 
- C pRect.top - 1 2 - C SBarWidth - 1 25; 

ShowControlC theScrollBar 2; 

ValidRectC &C *theScrollBar )->contriRect 2; 


DoGoAway( theEvent, whichWindow 2 
EventRecord*theEvent; 
WindowPtr whichWindow; 


INTEGER theWKind; 
theWKind = TGetWKindC whichWindow 2; 
if С theWKind == userKind ) 


if С whichWindow != TFrontWindowC userKind 22 
TSelectWindowC whichWindow 2; 

else if ( TrackGoAway( whichWindow, &theEvent-?where )) 
CloseDocWindowC whichWindow 2; 


else if С theWKind == toolKind 2 
if С TrackGoAwayC whichWindow, &theEvent->where 22 


lastToolsItem-; 
DelMenuItemC ToolsMenu, ItemOf( whichWindow, ToolsMenu 


2); 


) 


TDisposeWindowC whichWindow 2; 
) 


DoKeyStrokeC theEvent ) 


) 


EventRecord*theEvent ; 


INTEGER ch; 
LONGINT menuChoice; 


ch = € INTEGER 2€ theEvent->message k charCodeMask ); 
if € theEvent-? modif iers & cmdKey ) 
( ( theEvent— what != autoKey ) 


menuChoice = MenuKey( ch 2; 
DoMenuChoiceC menuChoice ); 


) 


DoUpdateC theEvent ) 


EventRecord*theEvent; 

GrafPtr savePort; 

WindowPtr  whichWindow; 

WDHandle theData; 

INTEGER theWK ind; 

GetPort( &savePort ); 

whichWindow = С WindowPtr OtheEvent-?message; 
theWKind = TGetWKindC whichWindow 2; 
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SetPort( whichWindow ); 
BeginUpdateC whichWindow 2; 


if С theWKind == userKind ) 
( 
EraseRect( &whichWindow->portRect ); 
г С GetWRefConC whichWindow ) != nil ) 


DrewGrowIconC whichWindow 2; 
DrawControlsC whichWindow ); 


) 
else if С theWKind == toolKind ) 
EraseRect( &whichWindow- portRect ); 


EndUpdate( whichWindow ); 
SetPort( savePort ); 


) 


DoActivateC theEvent ) 
EventRecord*theEvent ; 


WindowPtr whichWindow, 
theFrontWindow; 
WDHandle theData; 
INTEGER theWK ind, 
frontWK ind; 
whichWindow = С WindowPtr )theEvent-> message; 
SetPort( whichWindow ); 
theWKind = TGetWKindC whichWindow ); 
"i С theWKind == userKind ) 


theData = (WDHandle )GetWRefConC whichWindow 2; 
if € theData |= nil ) 


HLockC theData ); 
г ( theEvent- modif iers & activeFlag ) 


ShowControlCC *theData 2->5сВаг ); 


DisableItemC EditMenu, UndoItem ); 
DisebleItemC EditMenu, CutItem 2; 
DisableItemC EditMenu, CopyItem ); 
DisebleItemC EditMenu, PesteItem ); 
DisableItem€ EditMenu, ClearItem 2; 


o 
HideControlCC *theData )->scBar ); 


theFrontWindow = FrontWindow(); 
frontWK ind TGetWKind( theFrontWindow ); 
І ( frontWKind == systemKind ) 


EnableItemC EditMenu, UndoItem ); 
EnableItemC EditMenu, CutItem ); 
EnebleItemC EditMenu, CopyItem ); 
EnebleItemC EditMenu, PesteItem ); 
EnableItemC EditMenu, ClearItem 2; 


) 
HUnlockC theData ); 
DrawGrowIconC whichWindow ); 


) 
) 


INTEGER 

Item0f C whichWindow, whichMenu ) 
WindowPtr whichWindow; 
MenuHandle whichMenu; 
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) 


char  theTitle[ 255 |, 
theMenu [ 255 ); 

Boolean done; 

INTEGER theItem; 


GetWTitleC whichWindow, theTitle 2; 
for С done - false, 

theItem = 1; 

done == false; 

theItem** ) 


GetItemC whichMenu, theItem, theMenu ); 
( С strempC theTitle, theMenu ) == Ø ) 


done = true; 
theItem-; 


) 


returnC theItem 2; 


WindowPtr 
WindowOfC whichMenu, whichItem ) 


MenuHandle whichMenu; 
INTEGER whichI tem; 


char theTitlel 255 J, 
theMenu [ 255 1; 
Boolean done; 
INTEGER wantedK ind, 
theWK ind; 
WindowPeek loopWindow, 
wantedWindow; 


GetItemC whichMenu, whichItem, theMenu 2; 
if € whichMenu == WindowsMenu ) 
wantedKind = userKind; 
else 
wantedKind = toolKind; 


for € done = false, 
loopWindow = 
wantedWindow = windowList; 
done == false && loopWindow != nil; 
loopWindow = loopWindow->nextWindow ) 
theWKind = TGetWKindC loopWindow ); 
if С theWKind == wantedKind ) 


GetWTitleC loopWindow, theTitle ); 
if С strempC theTitle, theMenu ) == Ø ) 


wantedWindow = loopWindow; 
done = true; 


) 
) 


returnCC WindowPtr )wantedWindow ); 


void 


SetBoldC theDialog, bolditem ) 
DialogPtr theDialog; 
short bolditem; 

INTEGER itemType; 
Handle itemHandle; 
Rect itemRect; 


pascal void OutlineButton(); 


/* Get the OK button’s display rectangle, enlarge the 


251 


rectangle, and set up the useritem with this rectangle ); 
апа а pointer to the OutlineButton function. */ 


resource ‘MENU’ (2) ( 
GetDItemC theDialog, okButton, &itemType, &itemHandle, 2 


&itemRect ); textMenuProc, 
InsetRect( &itemRect, -3, -3 ); OxTFFFFFF3, 
SetDItemC theDialog, bolditem, userItem, enabled, 
С Handle )OutlineButton, &itemRect 2; “File”, 
) ( /* erray: 5 elements */ 
/* (1) */ 
pascal void “Мен”, noIcon, "N^, *^, plain, 
OutlineButtonC theDialog, theItem ) /* (2] */ 
DialogPtr theDialog; “New Tool”, noIcon, “Т”, *^, plain, 
INTEGER {Пе tem; /* [3] */ 
“Close”, noIcon, “W”, *", plain, 
INTEGER itemType; /* (41 */ 
Handle itemHandle; *-^ noIcon, "^, *", plain, 
Rect itemRect; /* [5] */ 
PenState — savePen; *Quit^, noIcon, *Q^, "^, plain 
/* Get the bounding rectangle of the OK button item ); 


and boldly outline it. */ 


resource ‘MENU’ (3) ( 
GetDItemC theDialog, okButton, &itemTupe, &itemHandle, 


&itemRect ); textMenuProc, 
GetPenState( &savePen ); üxTFFFFF80, 
PenSizeC 3,3 ); enabled, 
InsetRect( &itemRect, -4, -4 ); “Edit”, 
FrameRoundRect( &itemRect, 16, 16 ); { /* array: 7 elements */ 
SetPenStateC &savePen ); /* (1) */ 
) “Undo”, поїсоп, “7”, *", plain, 
/* [2] */ 
Listing: TWindowTester.R «~, nolcon, “”, **, plain, 
/* [3] */ 
/* “Cut”, noIcon, “X”, **, plain, 
*TWindowlester .г /* [4] */ 
x “Сору”, noIcon, “С”, **, plain, 
*Resources for а simple progrem to demonstrete usage of tool /* [5] */ 
windows “Paste”, noIcon, “V”, **, plain, 
*by using routines from the TWindow Manager. Tool windows are /* [6] */ 
windows *-^, поїсоп, *^, “”, plain, 
*that always float on top, typically for pelettes end tools. /* [7] */ 
* “Clear”, noIcon, "B^, *^, plain 
XWritten in MPW C 2.0 ) 
x ); 
ж Thomas Fruin 1988 
x resource ‘MENU’ (4) ( 
х fruin@éhlerul5 .BITNET University of Leiden 4, 
х  thomas@uvabick .UUCP University of Amsterdam textMenuProc, 
х dibs@wel] .UUCP allEnabled, 
х hol0066.AppleLink enabled, 
* 2:508/15.FidoNet The Netherlands “Windows”, 
x ( /* erray: 0 elements */ 
*TWindowTester is based on MiniEdit - Mini text ) 
editor,converted from ү: 
*the listing in Macintosh Revealed, vol II. As little as 
possible was resource “MENU” (5) ( 
*modified in the original program, although most of the ; 
functionalitu textMenuProc, 
*1$ no longer there. allEnabled, 
*/ enabled, 
“Tools”, 
resource ‘MENU’ (1) { /* array: 0 elements */ 
textMenuProc, ); 
Ox7FFFFFFD, 
enabled, resource ‘WIND’ (1080) ( 
apple, (50, 40, 300, 450), 
( /* array: 2 elements */ documentProc, 
/* [1] */ invisible, 
“About TWindowTester ...”, noIcon, *", *^, plain, goAway, 
/* [2] */ 0х0, 
“#—-# по1соп, *^, *", plain "Document * 
7 
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resource 'WIND^ (1001) ( 
(58, 533, 159, 606), 
altDBoxProc, 
invisible, 
noGoAway, 
0x0, 
“Tool ^ 


); 


resource 'CNTL' (1000) ( 
(-1, 395, 236, 411), 
0 


2 
=, 
0, 
0, 
scrollBarProc, 

0, 

*vertical scroll Баг” 


); 


resource “РІСТ” (128) ( 
2616, 
(0, 5, 217, 188), 


$^1101 A000 82А0 3039 A000 8Е01 000A 0000" 
$"0000 0200 0240 9800 1800 0000 0000 8600" 
$^С000 0000 0500 8600 ВС00 0000 0500 8600" 
$^BCO0 0106 ҒС00 0030 ЕҒ00 06ҒС 0000 78ЕҒ” 


%%0006 ЕС00 0078 ЕР 0 96FC 
%”ҒС00 0007 ЕҒ00 06ҒС 0000 
$0104 COFO 000A 0101 80ҒЕ 
%”0А01 03С0 ҒЕ00 0101 Е@Е@ 
%%0000 C8F0 0009 0107 EOFD 
$^0107 EOFD 0000 38Ғ0 0009 
$^13F0 2004 0101 8EFD 0001 
$°001Е FDOO 0107 80Ғ1 0008 
$^0003 20F1 0008 0700 38С0 
%%0008 0700 11Еб 00Ғ0 0000 
%”03Ғ0 0060 0000 5СҒ1 0008 
%%Ғ000 38F1 0008 0700 03Ғ0 
$^000C 0800 01-0 00ҒҒ ҒҒ00 
$"0000 C301 FFFF 8007 80F2 
$"83FF FFCO 03F1 000A 0600 
$^F000 0А06 0000 ВЕСЕ FFFF 
$^000F CFFE FFFO Ғ000 0A06 
$^ЕВЕ@ 000A 0600 0003 IFFE 
$^0003 ЗЕҒЕ 1FFC Ғ000 09ҒЕ 
$"F000 09ҒЕ 0003 ЗҒҒС ТЕЕС 
%”ЗҒЕС 7BFC Ғ000 Ø9FE 0003 
%”0ОҒЕ 0003 3FF8 F8FC Ғ000 
$"E3FC Ғ000 09ҒЕ 0003 3FF1 
%%0003 3FFO ТЕҒС Ғ000 OAFE 
%ФСОҒ1 000A FEØØ 041Ғ ЕТЕЕ 
$^0004 1FFF FFF9 EOF1 000A 
$°Ғ0С8 Ғ100 OAFE 0004 OFFF 
$^FEO00 0407 FFFF E038 Е 100 
$’FFCO 13Ғ1 0008 FE00 0501 
$^000А FDOO O4FF FFOO 0780 
$^3sFFC 0003 Ғ100 07Ғ0 0001 
$^0009 ҒВ00 0330 000Ғ FOF3 
%%003Ғ FCF3 0009 FBOO 03Ғ0 
%”ҒС00 0501 E201 FFFF 80Е4 
$°С703 FFFF COF4 000A ҒВ00 
$"F400 OAFB 0004 1EØF FFFF 
%%043С OFFF FFFO Ғ400 ОАЕВ 
$^F8F4 0009 ҒА00 O31F FFFF 
$"033F FFEF FCF4 0009 ҒА00 
$^0009 FA00 033Ғ FCOF FCF4 
$"003F FO8F FCF4 0008 Ғ(00 
$^FCF4 0008 ҒС00 0578 003Ғ 
$"FCO0 0532 003Ғ BCIF ЕСЕ4 
$^003F FEIF FCF4 0008 ҒС00 
$^FCF4 0008 ҒС00 0504 CO3F 
$"FCOO 0601 EO1F F83F Ғ8Сй 


0000 
OEEF 
0001 
0009 
0000 
0103 
0780 
0700 
00Е0 
ESF 1 
0700 
003Ғ 
0780 
0008 
000Ғ 
FOFO 
0000 
ЗЕЕВ 
0003 
FOOD 
ЗЕЕВ 
09ҒЕ 
OFFC 
0004 
FOES 
FEQQ 
FFF0 
BAFE 
FFFF 
F208 
OFFO 
0009 
OFF 
0008 
048Е 
FOF4 
0004 
FBF4 
033F 
0008 
0578 
39 1F 
0008 
050Е 
ҒЕЗЕ 
F500 


32EF 0006" 
0007 ҒС00" 
01Е0 Ғ000" 
0107 EØFD” 
1СЕй 0009" 
C4FD 0000" 
F100 0401" 
3600 0060" 
0000 70Ғ1" 
0008 0700" 
03Ғ0 000” 
ҒС00 13F 1" 
F200 0С08" 
0700 0007" 
СТЕЕ FFE" 
000A 0600" 
079Ғ ҒЕТЕ” 
Ғ000 09ҒЕ” 
3FFE 3FFC^ 
09ҒЕ 0003" 
FOFC Ғ000" 
0003 ЗЕЕ9" 
Ғ000 09ҒЕ” 
3FE1 FFFC^ 
Ғ100 QAFE" 
040Е FFFF” 
ICF1 000A" 
0004 03ҒЕ” 
8007 80F2" 
09FD 0003" 
EF00 02E9" 
ҒВ00 0378" 
FFF3 0008" 
ЕС00 0501" 
ОТЕЕ FFE" 
000A FBOO" 
181F FFFF^ 
0009 FADO" 
FF87 FCF4" 
FC00 0530" 
003Е 038Ғ” 
FCF4 0008” 
ҒС00 0507" 
ОЗЕ FF3F” 
FCF4 000С” 
@СЕС 0006" 
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$"01E0 1FFC ТЕҒ9 EOF5 0008 ҒВ00 0508 OFFE” 
$^ТЕЕ1 EOFS 0008 FBG 053C ВЕРЕ TFFO CBF5" 
$^0008 FBOO 053С 07FF FFEO 1СҒ5 0008 ҒВ00" 
%%0518 0ЗҒҒ FFCO ЗАҒ5 0008 ҒВ00 0507 81FF/ 
$"FF80 17F5 0008 FBØØ 0507 80ҒҒ ҒҒ00 OEF5" 
%”000С FBOO 0603 603F ҒС00 04С0 Ғ600 0ВҒА” 
%%0005 FOOF Ғ000 01Е0 Ғ600 0ВҒА 0000 FOFE" 
%%0001 01Е0 Ғ600 0СҒА 0006 6С00 0020 00СҒ” 
%”ҒОҒТ 000С FAO0 061Е 0000 7000 ЗЕЕС F790" 
%”ОСҒА 0006 1Е00 00-0 OOFF FFF7 0000 FASO" 
$^070С 8001 Е001 ҒҒҒҒ 80-8 0000 ҒА00 0701" 
$"C001 C603 FFFF COF8 0000 FA00 0703 8000" 
$^8F07 FFFF EOF8 0000 FAO0 0701 0000 1F8F" 
$"FDFF FOF8 000A Ғ700 041Ғ BFFC FFFO F800" 
%”0АҒТ 0004 1ҒОҒ F87F F8F8 000A Ғ700 040Ғ” 
$” 1FFØ ТЕЕ8 Ғ800 00Ғ7 0007 063Ғ E4FF ҒС00" 
$^0030 ҒВ00 0СҒ6 0006 ЗЕС8 FFFC 0000 78ҒВ” 
$^000C F600 063Ғ 99ҒҒ ҒС00 0078 ҒВ00 0СҒ6" 
$^0006 3F39 FBFC 0000 32-8 000С Ғ600 063C” 
$’71F 1 ҒС00 0007 ҒВ00 OCF6 0006 ЗЕТЗ COFC" 
$"0000 OEFB 0000 Ғ600 073Ғ 7330 ҒС00 0004" 
$^COFC 0000 Ғ600 073Ғ FOE3 ҒС00 0001 EOFC” 
%%0000 Ғ600 073F ЕЗСТ FCOO 0001 EOFC 000Ғ” 
$^F800 0530 003Ғ EF8F FCFE 0000 C8FC 000Ғ” 
$"F800 0578 00ІҒ FFIF F8FE 0000 1СЕС 000Ғ” 
$^F800 0978 001F F83F Ғ840 0000 38FC 000Ғ” 
$^F800 0932 000Ғ ЕСТЕ FOEO 0000 13FC 0010" 
$^F800 0А07 000Ғ ҒЕТЕ Ғ100 0000 0780 Ғ000" 
%”10Ғ8 000А 0Е00 0ТЕҒ 7ҒЕ0 8800 0007 80Ғ0” 
$"0010 Ғ800 0404 С003 FFFF С074 0000 0360" 
%“Ғ000 10Ғ8 0006 01Е0 O1FF ҒҒ80 2ЕҒЕ 0000" 
$"FOFD 0010 Ғ800 0601 Е000 FFFF 001С ҒЕ00" 
%”00Ғ0 Ғ000 OFF7 0009 0800 3FFC 0009 8000" 
$^006C Ғ000 ØFF7 0009 3С00 0ҒҒ0 0003 С000" 
$^001E Ғ000 OEF7 0000 3CFD 0004 03С0 0000" 
$^1EFD 0010 F700 0А19 0000 0180 0180 0000" 
$"0080 ҒЕ00 10F7 000A 0380 0003 С000 ІҒЕ0" 
%”0003 COFE 0010 Ғ700 0А07 4000 07Е0 001Ғ” 
$"F800 03С0 ҒЕ00 10F7 000А 02Е0 0007 Е001" 
$^"FFFE 0001 80ҒЕ 0000 Ғ700 0701 С000 07Е0" 
$^ОЗЕЕ FFFB 0000 Ғ600 0798 0003 C407 ҒҒҒҒ” 
$^80FC 000Ғ Ғ600 093С 0001 8E0F FFFF С000" 
$°01РЕ 0010 Ғ600 OA3C 0000 1Е1Е FFFF Е000" 
$^0380 ҒҒ00 10F6 000A 1900 003С IFFF FFEO" 
%”0006 COFF 0010 Ғ600 0А03 8000 383F ҒҒҒҒ” 
%%-000 0С60 ҒҒ00 10Ғ6 000A 0700 0010 ЭҒҒЕ” 
$"FFFO 0018 30FF 0010 Ғ600 0002 ҒЕ00 067Ғ” 
$“РЕТЕ Ғ800 3018 ҒҒ00 0СҒ2 0006 ТЕРС 3FF8" 
90060 OCFF 000С Ғ200 O67F F81F Ғ800 С006" 
$^FFO0 0СҒ2 0006 ТЕЕ@ 6FF8 00С0 0ЗЕҒ 000С” 
97-200 O87F ЕЙЕҒ F800 Е001 8000 0СҒ2 0008" 
$“7FC1 E7F8 0080 00С0 000С Ғ200 087F 81С7" 
%”Ғ800 9800 6000 0СҒ2 0008 7Е04 07Ғ8 018С” 
$^0030 000С F200 087F OEOF Ғ803 C600 1800" 
%”0СҒ2 0008 TFOF 9FF8 0663 000С 000С F200" 
%”083Ғ DFFF FOCC 3180 0600 9800 1800 8600" 
$"0000 0900 С000 8600 0500 0900 BCOO 8600" 
%70500 0900 800 010С Ғ200 O83F FFFF Е1Е8" 
$^1980 0300 0СҒ2 0008 1FFF ҒҒЕЗ 300F 0001" 
$^800С Ғ200 08ІҒ FFFF E618 0600 00С0 0СҒ2" 
$0008 OFFF FFCC 0С0С 0000 600С Ғ200 0807" 
$"FFFF 9806 1800 0030 0СҒ2 0008 O3FF FF30" 
$^0330 0000 700С Ғ200 0801 FFFE 7001 Е000" 
$^0000 08Ғ1 0007 ТҒҒ8 5800 С000 0190 ØBF 1" 
$"0002 1ҒЕй 4СҒЕ 0001 0330 09ЕҒ 0000 66ҒЕ” 
970001 0660 SAFO 0001 0183 ҒЕ00 010С С00А” 
$^-000 0603 0980 0000 1980 ØAFØ 0006 OTEC" 
$“С000 0033 000А Ғ000 0607 E660 0000 6600" 
$"0AFO 0006 B7E3 3000 00СС 000А Ғ000 0603" 
$^C598 0001 9800 BAFS 0006 018Е СС00 0330" 
$^0009 ЕҒ00 051Е E600 0670 0009 ЕҒ00 0530” 
$^B300 0С08 0009 ЕҒ00 053В Ғ080 19CC 0009" 
$"EF00 0517 FCCO ЗЗЕб 0009 ЕҒ00 050Ғ ҒЕ60" 
$"67F3 0009 ЕҒ00 0518 F330 CFF9 8009 ЕР 0" 
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$^0533 F199 ОҒҒС С009 ЕҒ00 0567 EOCF ЗҒҒЕ” { /* array DITLerray: 7 elements */ 


$^6009 ЕҒ00 05СС СТЕб 7FFF 300A Ғ000 0601" /* (1) */ 
$^980F FOFF FF30 ØAFØ 0006 O3CC 0ҒҒ9 FFFE” (27, 270, 48, 341), 
%%700А Ғ000 0606 660F FFFF FCDO @AF0 0006" Button ( 
%%0433 OFFF FFF9 900A Ғ000 0604 1987 ҒҒҒҒ” enabled, 
$^r310 GAFO 0006 040С СЭҒҒ FFE6 100A Ғ000" “оқ” 
$^0604 0663 FFFF CCDO ФАҒ0 0006 0403 ЗТҒҒ” }, 
$^FF99 000А Ғ000 0604 010Ғ FFFF 3300 @AF0" /% 121 */ 
%%0006 0400 СЕРЕ FE67 DOOA Ғ000 0604 0067" (56, 66, 73, 174), 
$^FFFC СҒ50 SAFO 0006 0400 33FF F99A 500А” StaticText ( 
%9Ғ000 0604 0019 FFF3 3250 SAFO 0006 0400" disabled, 
$^0CFF E662 500A Ғ000 0604 0006 ТЕСС C250" "TWindowTester^ 
ФО АҒ0 0006 0400 O33F 9982 500A Ғ000 0604" ), 
%%0001 9F33 0250 BAFS 0006 0400 00СЕ 6602" /* [3] */ 
%%500А Ғ000 0604 0000 64CC 0250 0АҒ0 0006" (189, 19, 226, 266), 
$^0400 0031 9806 500A Ғ000 0604 0000 1830" StaticText ( 
%%0С00 OAFO 0006 0400 000Е 6019 900A Ғ000" disabled, 
$^0604 0000 04С0 3310 OAFO 0000 04ҒЕ 0002" “Originally written for VAMP, * 
$^8066 500A Ғ000 0004 ҒЕ00 0280 CCDO SAFO" “the Dutch Mac programmers group.” 
60000 04ҒЕ 0002 8199 900A Ғ000 0004 ҒЕ00" | 
$^0283 3330 OAFO 0000 O4FE 0002 8666 600A" /* [4] */ 
$?F000 0004 ҒЕй0 028С CCCO BAF 0000 04ҒЕ” (99, 60, 116, 172), 
$^0002 9999 СОВА Ғ000 0004 ҒЕ00 0283 3340" StaticText ( 
DAFO 0000 O4FE 0002 E626 400A Ғ000 0004" disebled, 
$^FEO0 02СС 0С40 OAFÜ 0000 04ҒЕ 0002 9818" “bu Thomas Fruin” 
$ CODA Ғ000 0004 ҒЕ00 0280 3180 OAFO 0000" : 
$^06FE 0002 E063 000A Ғ000 0003 ҒЕ00 02С0" /* [5] */ 
%%С600 ØAFØ 0006 0180 0000 818C 0009 ЕҒ00" (117, 34, 135, 196), 
%%05С0 0000 0318 0009 EFOO 0560 0000 0630" StaticText ( 
$^0009 ЕҒ00 0530 0000 0С60 0009 ЕҒ00 0518" disabled, 
%%0000 18С0 0009 ЕҒ00 050C 0000 3180 0009" "Leiden, Тһе Netherlands” 
%%ЕҒ00 0306 0000 63FF 0009 ЕҒ00 0303 0020" }, 
$^C6FF 0009 ЕҒ00 0301 8031 BCFF 0008 ЕЕ00" /* (6) */ 
%%02С0 1818 FFOO 08ЕЕ 0002 600Е 30FF 0008" (148, 68, 164, 169), 
%”ЕЕ00 0230 0460 ҒҒ00 08ЕЕ 0002 1800 COFF" StaticText ( 
$^0008 ЕЕ00 020С 0180 ҒҒ00 ОТЕЕ 0001 0603" disabled, 
$^FE00 0ТЕЕ 0001 0306 ҒЕ00 0ТЕЕ 0001 018С” “20 April 1988” 
$^ЕЕ@@ 06Е0 0000 08ҒЕ 0006 EDOO 0070 ҒЕ00" }, 
$"06ED 0000 20FE 00А0 008Ғ А200 B3FF" /* [7] */ 
); (9, 158, 226, 341), 
Picture ( 
resource 'DLOG^ (128) ( disabled, 
(62, 77, 312, 437), 128 
dBoxProc, ), 
invisible, /* [8] */ 
noGoAway, (27, 270, 48, 341), 
0x0, UserItem ( 
128, disabled 
“About” ) 
); | } = 
resource ‘DITL’ C128) ( | ч 
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Procedures 


Pascal Procedures 
Keyboard Wars! 


ADB, Keyboards & TypingBattle 

One of the most obvious change to the Mac SE and the Mac 
// has been the redesign of the keyboard and mouse interface. 
There are no longer 2 separate interfaces for the mouse and the 
keyboard, each of which could handle only 1 device. Instead the 
mouse and keyboards are connected through the new Apple 
Desktop Bus (ог ADB). All of Apple's new computers (Mac SE, 
Mac //, Apple //gs) use ADB. This interface allows multiple 
ADB devices to be connected to the computer at the same time. 
Thus a Mac SE could have 2 keyboards, a mouse and a third-party 
ADB device (perhaps a graphics tablet) all connected to the 
computer at the same time. While most programs will recognize 
a key being pressed no matter what keyboard (an А is always an 
A), a program can be written that recognizes the difference 
between keyboards and acts accordingly. This article will 
expand on various ideas involving the ADB, the new keyboards, 
and the sample program. The sample program that is provided is 
TypingBattle, a multiple keyboard typing contest. 


Apple Desktop Bus 

The Apple Desktop Bus is a low-speed input-only interface 
for the new computers from Apple. The Mac SE and the //gs have 
a single ADB port while the Mac // has two ports. Each ADB 
device (except for the Mouse which must be the last item on a 
ADB line) is a pass through device, similar to the SCSI interface. 
The first ADB keyboard is plugged into the computer's ADB 
port, the next ADB keyboard is plugged into the previous 
keyboard (or a second computer port if there is one). Logically 
upto 16 ADB devices can be connected to a single Computer. In 
practice, however, the signal is not powerful enough to go 
through that many devices. Depending on what style of keyboard 
is being used, currently 3-5 keyboards and a mouse is the 
maximum configuration. 

ADB devices communicate with the computer using the 
ADB Manager and special ADB commands. Normally ADB 
communication is the domain of the ADB device drivers. The 
Macintosh Start Manager finds all the ADB devices connected to 
the computer and places that info into an ADB device table. It 
then initializes any ADB device drivers in the System file. These 
drivers (stored as ' ADBS' resources) will then handle апу ADB 
communication. 

The Mac // and Mac SE System Files contain two standard 
ADB device drivers, the mouse driver and the universal keyboard 
driver. The mouse driver handles all mouse movements. It also 
handles all clicking of the mouse button and issues standard 
MouseDown and MouseUp events to the Event manager. While 
two mice can be connected to the Mac //, the mouse driver was 
not designed to be able to differentiate between mice or pass this 
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| have not yet begun to fight. 


David Score: 0 


| have not yet bequn to fight. 


julie Score: 0 


x i khave not yet bequin to fight 


Fig. 1 Two keyboards battle for typing supremacy 


information over to the application. No information is passed in 
the MouseUp or MouseDown event record to explain which 
Mouse was clicked. Still, for a bit of amusement, connect to two 
mice to the Mac // and give them to two different people. The 
cursor will move with each move of either mouse, causing much 
frustration. 

The ADB universal keyboard driver handles any keys being 
pressed or released on an ADB keyboard. It generates a 
KeyDown or a KeyUp event for the Event Manager. However 
unlike the mouse driver, the keyboard driver passes along infor- 
mation explaining, not only what key was pressed, but on which 
keyboard. Prior to the ADB, the Message field of a KeyDown/ 
KeyUp Event record contained the ASCII Character in the first 
byteand the Virtual Key Code in the second byte. With ADB, the 
Message field's first and second bytes are the same, while the 
third bye contains the ADB address of the keyboard that was 
used. This information is the basis of the sample program, 
TypingBattle. Two globalbyte variables are now associated with 
the ADB Manager; KbdLast, the ADB address of the last key- 
board used and KbdType, the Keyboard type of the last keyboard 
used. 

While the sample program only uses the Event record for 
information about the multiple keyboards, the ADB manager can 
be accessed directly. The CountADB function returns the total 
number of ADB devices connected to the computer. GetIndADB 
(based on the device count from 1 to CountADB number) and 
GetADBInfo (based on the ADB address of a device) return 
information about the Device Type, ADB address, service rou- 
tine address and data area address. Other ADB Manager calls 
(ADBRelnit, ADBOp and SetADBInfo) should not be used 
directly by an application. Any non-keyboard or non-mouse type 
of ADB interface would use these commands in it'S own ADB 
device driver. 
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The usage of the ADB has yet to be fully recognized. For a 
hardware developer, designing an ADB device has several ad- 
vantages. For example, the majority of the current graphics 
tablets available for the Mac connect to the serial ports, requiring 
special software drivers (which do not always work with all 
software packages) and the loss of that serial port for other uses. 
An ADB graphic tablet thatemulates an ADB mouse would work 
without any special software drivers or loss of port. For the same 
reasons, an ADB Piano Keyboard would easily interface into all 
existing Music Packages. 


Keyboards 

There are currently 3 ADB keyboards that can be used on the 
Mac SE & Mac //. The standard ADB Keyboard is essentially a 
duplicate of the older non-ADB MacPlus keyboard. It has a 
standard keyboard layout with cursor keys and a Numeric Key- 
pad. Programs that were written to use the MacPlus cursor keys 
will function identically on the standard ADB Keyboard. 

Most people do not realize the second ADB keyboard will 
work on the Мас SE & Mac //. The Apple //gs uses the ADB 
interface. It uses the same Mouse as the Mac SE & Mac //. 
However the //gs has it'S own ADB keyboard. This keyboard is 
similar in layout to the standard ADB keyboard, except slightly 
smaller. Remember that any ADB computer can work with any 
ADB device. While only a large lab would have both the 
Macintosh and //gs, it is sometime convenient to know that in a 
rush, either computer can use the other keyboard. 

The third ADB keyboard is the Extended ADB Keyboard 
(sometimes still referred to by it's development code name 
"Saratoga"). Ithas all the features of the standard ADB Keyboard 
plus additional keys. These additional keys include 15 Function 
# keys, a Control Key, and 6 Special purpose keys. 

The 15 Function key, called F1 through Е15, are across the 
top of the keyboard. The first four function keys, F1, F2, F3 and 
F4, are designed to be assigned the functions Undo, Cut, Copy 
and Paste. These functions are printed next to each key on the 
keyboard. The Virtual Key Codes (ie. the third Byte of the 
Longint passed in the Event field of the eventrecord for keyboard 
events) of these keys are $7A, $78, $63 and $76. New programs 
should recognize these Virtual Key Codes, and implement the 
functions accordingly. According to Apple’s Guidelines, the F5 
thought F15 keys are intended to be defined by the user, not by 
the Application. Utilities like QuickKeys by CE Software or 
Apple’s promised MacroMaker allow the user to redefine any 
key to a specific action. Still, if the developer wishes to do so, a 
program could use these keys for it's own purpose. 

The Control key was added for compatibility with applica- 
tions that communicate with another operating systems (ie. 
terminal packages). Pressing the Control key sets bit 12 of the 
modifier field of the event record for keyboard events. Since the 
Macintosh OS does not use the concept of Control characters, 
except for a communication application, this key should not be 
used by Macintosh applications. 

Theother 6 Special Keys are intended to give the user greater 
control of his application. Each application must handle each 
. Special key in it'S own way. The following are the Keys, their 
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Virtual Key Codes and general guidelines for usage. 

The Home key ($73) moves the user to the home position in 
theapplication. Ina word processor, this key may move the scroll 
bar to the top of the document. In a database, this may move the 
display to the first field or the first record. The End key ($77) 
moves the user to the end position in the application. In a word 
processor, this key may move the scroll bar to the bottom of the 
document. The Page Up key ($74) and Page Down Key ($79) 
moves the user to the next page (up or down) in the application. 
In a word processor, these keys would be equivalent to clicking 
in the page up (or down) region of the vertical scroll bar. In a 
database, these keys may move the user to the previous or next 
record. According to Apple Guidelines, the Home, End, Page Up 
and Page Down keys should not effect the actual position of the 
current insertion point. 

The Help key ($72) allows the user to request help from the 
program. A good usage of this key would be invoke the About 
menu (or Help menu, if one exists). The Forward Delete, or Fwd 
Del, key ($75) performs similar to the Backspace key. In a word 
processor, when the Backspace key is pressed, a character before 
the current insertion point is deleted. Using the Forward Delete 
key in the same situation, a character after the current insertion 
point should be deleted. Use this key carefully. It is a bad idea 
to allow the user to delete something he can not see (for example, 
in a database, delete the next unseen record). 


TypingBattle 

TypingBattle is a sample program designed to show how to 
handle more than one keyboard. It also implements the special 
keys of the Apple Extended Keyboard. The game is a simple 
typing speed contest. First the program prompts each userto type 
his name from his keyboard. This tells the application the 
number of players, the name of each player and the ADB address 
of each player's keyboard. To start a round, each player must 
press the return key (so that no one is surprised). Roughly three 
seconds later, a random typing Sample is shown. The first player 
to correctly type it (including correct punctuation and case), and 
then press return, wins the round. The player can backspace over 
any mistakes, up until the time he presses return. Then, his line 
is judged for correctness. The round continues until a winner 
finishes or everyone has entered a mistake. The users can use the 
mouse to select a new round or start a new configuration. The 
About Menu or the Help Key will display the About Box. 


Last Comments 

* The program uses MultiLine, a simple Editunit. Text 

Edit was not designed to have multiple edit fields 

open at the same time. 

Modifying the Resource source file or ResEdit can be 

used to add additional typing Samples. 

* Whenever connecting new ADB devices, always 
power down the computer. А simple reset is not 
enough for the system to recognizes when new ADB 
device have been connected or detached. 

* In the food for thought area, the sample program 
show how to use multiple keyboards with a single 
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screen. What about multiple keyboards and multiple 
screens? The ADB working together with the Mac / 
/ multiple Video cards would give a true multiuser 
interface to the Mac. For fun, a MazeWar's type of 
game would be simple to do. On the serious side, a 
database package that handled multiple screens/key- 
boards would have it's advantages. The hardware 
would be much cheaper than setting up multiple 
Mac's over Appletalk, while the performance might 
even increase (no time spent communicating be- 
tween computers). Any takers? 


( TypingBattle by Steve Sheets 11/15/87) 
Simple Demonstration of Multible Keyboards. ) 
ІСЕР TypingBattle; 


Multiline; 
CONST 
MaxAllow = 5; 
AboutID = 600; 
TextID = 600; 
LineID = 681; 
AppleMenuID = 1; 
FileMenuID = 2; 
EditMenuID = 3; 
WindowH - 480; 
VEdge = 40; 
CenterTop = 40; 
Edge - 10; 


(Unit to handle simple editing) 


(Мах Number of Players) 
(Various Resource IDs) 


(Placement Constants) 


Playoff = 50; 

ТТор = - 15; 

RTop = 5; 

WTop = 35; 

TimeCount = 180; (Timer to stert round) 
(Variables: Menus, Done Flag, Number Players, Main Window, 
Status of дате, Number of Samples, Number Players done, lots 
strings, arrays holding Players Scores, Who's Done, Names & 
Bus IDs end finally Edit fields holding Message, Names & 
Text.) 

VAR 

AppleMenu, FileMenu, EditMenu : MenuHandle; 

Done : boolean; 

theNum : integer; 

MyWindow : WindowPtr; 

Status, NumSamples, NumDone : integer; 

WelStr, ScoreStr, PreStr, WinStr, PressStr : str255; 

NoOneStr, EnterStr, SepStr, theTitle : str255; 

Score : ARRAY[1..MaxAllow] OF integer; 

isDone : ARRAY[1..MaxAllow] OF boolean; 

theName : ARRAY([1..MaxAllow] OF str255; 

theBus : ARRAY[1..MaxAllow] OF integer; 

MessRec : MLRec; 

NameRec, TextRec : ARRAYL1. .MaxAllow] OF MLRec; 


(Returns Number Of Samples Cie. Number of strings in the STR' 
resource.) 
FUNCTION GetNumSamples : integer; 
TYPE 
WP = “integer; 
= ^WP; 


BEGIN 

М := POINTERCGetResource( ‘STR®’, TextID)); 
Ge tNumSamp les {= Wee: 
Re leaseResource(POINTER(W)); 

END; 


(Given M CLongint Message field of Keydown event), return B 
(Bus ID), V (Virtual code) & C (Key pressed). } 
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PROCEDURE CalcKey (М : longint; 
VAR B, V : integer; 
VAR C : char); 


BEGIN 
С := Chr(M MOD 256); 
B := (M DIV 65536) MOD 256; 
V := (M DIV 256) MOD 256; 
END; 


(Do About Box.) 
PROCEDURE DoAbout; 
VAR 


n : integer; 
BEGIN 
n := AlertCAboutID, NIL); 
END; 


(Initialize variables) 

PROCEDURE DoSetup; 

BEGIN 
GetIndString(WelStr, LineID, 1); 
GetIndString(ScoreStr, LineID, 2); 
GetIndString(PreStr, LineID, 3); 
GetIndString(WinStr, LineID, 4); 
GetIndString(PressStr, LineID, 5); 
GetIndString(NoOneStr, LineID, 6); 
GetIndStringCtheTit]e, LineID, 7); 
GetIndStringCEnterStr, LineID, 8); 
GetIndString(SepStr, LineID, 9); 
NunSamples := GetNumSamples; 
AppleMenu := GetMenuCAppleMenuID); 
AddResMenuCAppleMenu, ‘DRVR’); 
InsertMenuCAppleMenu, 0); 
FileMenu := GetMenu(FileMenuID); 
InsertMenu(F i leMenu, 9); 
EditMenu := GetMenuCEditMenulD); 
InsertMenuCEditMenu, 9); 
DrawMenuBar ; 
InitCursor; 
MyWindow := NIL; 
Done := false; 

END; 


(Given an integer H & V, make а centered rectange R.) 
PROCEDURE MakeRect (VAR R : rect; 
h, v : integer); 
VAR 


N : integer; 
BEGIN 
М := Cscreenbits.bounds.right - screenbits.bounds. left - 
H) DIV 2; 
SetRect(R, М, VEdge, N + H, VEdge + V); 
END; 


(Handle Special Keys, return true if none was pressed. Іп 
this case, only handle Help by calling About Box. Note the 
Hex Codes.) 


FUNCTION NotSpecKeys (Virtual : integer) : boolean; 
BEGIN 
IF Virtual = $72 THEN 

BEGIN 


DoAbout ; 
NotSpecKeys := false; 


ELSE 
NotSpecKeys := true; 
END; 


(Finds out who is playing Cie. set Names & Bus IDs) or quit 
game Cie. Done true).) 


PROCEDURE GetPlayers; 
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CONST 


ConV = 85; 
ConH - 360; 
DLOff = 15; 
kOff = 25; 
КТор = 15; 
kHi = 20; 
LineLeft = 20; 
butBot = -15; 
OKLeft = 90; 
QUITLeft = 210; 
Voff = 15; 
VAR 


tempPort : Grafptr; 

myW : WindowPtr; 

cont, F2 : boolean; 

tempEvent : EventRecord; 

tempWindow : windowptr; 

tempCode, tempVirtual : integer; 
tempChar : char; 

OKcon, QUITcon, tempCon : ControlHandle; 
Lines : ARRAYL[1..MaxAllow] OF MLRec; 


PROCEDURE DoBox (V : integer); 
VAR 
R2 : Rect; 
BEGIN 
WITH Lines(V] DO 
BEGIN 
R2.left := Fr.left - 1; 
R2.right := Fr.right + 1; 
R2.top := Fr.top - 1; 
R2.bottom := Fr.bottom + 1; 
IF V > theNum THEN 
PenPat(Gray); 
FrameRect(R2); 
PenPatCBlack); 
| ЕМО; 
END; 


PROCEDURE CheckoK ; 
BEGIN 
IF CtheNum > 0) AND CtheNum <= MaxAllow) THEN 
HiliteControlCOKcon, 02 


ELSE 
HiliteControlCOKcon, 255); 
END; 
PROCEDURE RegKey (V : integer; 
С : Char); 
VAR 
count, L : integer; 
BEGI 
count := 0; 


FOR L := 1 TO theNum 00 
IF theBus(L] = v THEN 
count := L; 
IF count - 0 THEN 
BEGIN 
IF BE < MaxAllow) AND COrdCC) >= 32) THEN 
theNum := theNum + 1; 
theBus[theNum] := V; 
Lines[theNum].St := ' “, 
Lines[theNum].St[1] := C; 
Lines[theNum].Cr := °’; 
MLresetCLines[theNum1); 
DoBoxCtheNum); 
CheckOk ; 
END; 


MLcharCLines[count], С), 
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IF Lines(count].St = ^’ THEN 
BEGIN 
IF count € theNum THEN 


FOR L := count TO theNum - 1 DO 


IN 
МІ (ехісі ілес (11, Lines(L + 1].34); 
theBus[L] := theBusIL + 11; 
END; 
Lines[theNum].St := °’; 
END; 


Lines{theNum].Cr imo oos 
MLresetCL ines[theNum 12; 
theNum := theNum - 1; 
DoBoxCtheNum + 1); 
CheckOk ; 
END 
END; 
END; 


PROCEDURE DoGPSetup; 
VAR 


nn, count : integer; 
$ : str255; 
Bx : rect; 
BEGIN 
nn :- Солу + (MaxAllow * kOff); 
MakeRect(Bx, ConH, пп); 
myW := NewWindow(NIL, Bx, ””, true, 1, POINTERC- DD, 
false, 0); 
SetPort(muW); 
SetRect(Bx, OKLeft, nn - 20 + butBot, OKLeft + 60, nn + 
butBot); 
GetIndString(S, LineID, 10); 
OKcon := NewControl(myW, Bx, S, true, 0, В, 0, 0, 0); 
SetRect(Bx, QUITLeft, nn - 20 + butBot, QUITLeft + 60, 
nn + butBot); 
GetIndString(S, LineID, 11); 
QUITcon := NewControl(muW, Bx, 5, true, 0, 0, 0, 0, 0); 
cont := false; 
theNum := 0; 


FOR count := 1 TO MaxAllow DO 
BEGIN 
nn := (count * КОРР) + DLOff; 
SetRect(Bx, LineLeft, nn, ConH - LineLeft, пп + kHi); 
MLinitCLines[count], '^, '^, 4% Bx, false); 
END; 
END; 


BEGIN 
DoGPSetup; 
СһескОк; 
КЕРЕАТ 
SystemTask; 
IF GetNextEventCeveryEvent, tempEvent) THEN 
BEGIN 
IF tempEvent.what = mouseDown THEN 
BEGIN 
F2 := true; 
IF FindWindowCtempEvent.where, tempWindow) = inContent 


HEN 
BEGIN 
GlobalToLocalCtempEvent . where); 
IF FindControlCtempEvent.where, туй, tempCon) € 0 THEN 
IF TreckCOntrolCtempCon, tempEvent.where, NIL) ‹ Ø 


BEGIN 
IF tempCon = QUITcon THEN 
BEGIN 


THEN 


END 
ELSE IF tenpCon - ОКсоп THEN 
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BEGIN 
Cont := true; 
FOR tempCode := 1 TO theNum 00 


theName [tempCodel := 
Lines{tempCode].St; 
F2 := false; 
END; 
END 
ELSE 
F2 := false; 
END; 
IF F2 THEN 
sysbeep( 1); 
END; 
IF tempEvent.what = keydown THEN 
BEGIN 


CalcKeyCtempEvent.message, tempCode, tempVirtual, 
tempChar ); 
IF NotSpecKeys(tempVirtual) THEN 
RegKeyCtempCode, tempChar); 


д 
IF tempEvent.what = updateEvt THEN 
IF myW = WindowPtrCtempEvent.message) THEN 
BEGIN 
GetPortCtempPort); 
SetPor tCnyW); 
BeginUpdate(myW); 
MoveToCCConH - StringWidthCEnterStr)) DIV 2, 
kTop + Voff); 
DrawString(EnterStr); 
FOR tempCode := 1 ТО MaxAllow DO 
BEGIN 
MLupdateCL ines [tempCode 10; 
DoBox( tempCode ); 
END; 
DrawControls(myW); 
EndUpdateCmyW); 
SetPort(tempPor t); 
END; 


END; 

UNTIL cont OR done; 
Ki1l1ControlsCmyw); 
DisposeWindowCmyw ); 
END; 


(Dispose Window Cif any), get Players Cif any), if so create 
the Window апа) 
( Edit fields for the next game.) 
PROCEDURE DoConf igure; 
VAR 


tempRect : Rect; 
flag : boolean; 
count : integer; 
Bx : rect; 
BEGIN 
IF MyWindow <> NIL THEN 
BEGIN 


DisposeW indowCMyW indow) ; 
MyWindow := NIL; 
END; 


GetP layers; 


IF NOT done THEN 
BEGIN 

MakeRect(tempRect, WindowH, WTop + CtheNum * 
Playoff >); 

MyWindow := NewWindow(NIL, tempRect, theTitle, 
false, 1, POINTERC- D, false, 0); 

SetPor t(MyWindow); 

Bx. left := Edge; 

Bx.right := WindowH - Edge; 

Вх. top := Edge; 

Bx. bottom := Bx.top + Hi; 
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MLinitCMessRec, '', °’, ' *', Bx, false); 
FOR count := 1 ТО theNum DO 
BEGIN 
Bx. top := (count * PlayOff) + TTop; 
Bx.bottom := Bx.top + Hi; 
Score[count] := 9; 
MLinitCNameReclcount], CONCATC theName [count], 
ScoreStr), '', ' °, Bx, false); 
Bx.top := (count * PlayOff) + RTop; 
Bx.bottom := Bx.top + Hi; 
MLinitCTextRec[count], '^, 9, ° *, Bx, true); 
END; 
ShowW indowCMyW indow ); 
END; 
END; 


(Start a game by setting status to 1, setting correct message, 
clearing score, } 
( text and done flags.) 
PROCEDURE DoStart; 
VAR 
count : integer; 
tempPort : GrafPtr; 
BEGIN 
GetPortCtempPort); 
SetPor t CMyWindow); 
Stetus := 1; 
MLtext(MessRec, WelStr); 
FOR count := 1 ТО theNum 00 
BEGIN 
Score[count] := 0; 
MLtextCNameRec[count], 707); 
MLtextCTextRec[count], °’); 
IsDone(count] := false; 


SetPor t(tempPort); 
END; 


(Handle updating the window by calling Edit fields update.) 
PROCEDURE DoUp; 


count : integer; 
tempR : rect; 
BEGIN 
SetRectCtempR, Ø, Ø, 1000, 1000): 
EreseRect(tempR); 
MLupdateCMessRec); 
FOR count := 1 TO theNum DO 
BEGIN 
MLupdateCNameRec [count 1), 
MLupdaeteCTextRec [count 10; 
END; 
END; 


(Flush the Event buffer of Keydowns. } 
PROCEDURE FlushKeys; 
BEGIN 
FlushEvents(keyDownMask, 9); 
END; 


(Depending on Game Status, handle the Key down. Who is 
Players number (not bus ID). Status 1 is everyone waiting for 
811 Players to press return for the next round.Status 2 has 
everyone playing.) 
PROCEDURE DoKey (Who : integer; 

Key : char); 
VAR 


11 : longint; 

Sp : str255; 

count : integer; 

dummy : boolean; 

tempPort : GrafPtr; 
BEGIN 


GetPor t( tempPort); 
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SetPor t CMyWindow); 
SetPor tCMyWindow); 
IF (Status = 1) AND (Key = Chr(13)) THEN 
BEGIN (Player Pressed return.) 
IsDone{who] := true; 
dummy := true; 
FOR count := 1 TO theNum Do 
dummy := dummy AND IsDone[count ]; 


(If everyone pressed return, wait awhile, then display the 
Sample, flush any old key events & go to Status 2.) 


IF dummy THEN 
BEGIN 
ML text(MessRec, PreStr); 
11 := Tickcount; 
NumDone := 0; 
FOR count := 1 Т0 theNum DO 
BEGIN 
IsDone([count] := false; 
MLtextCTextRec[count], ““); 
END; 
count := (Random MOD NumSamples) + 1; 


GetIndString(Sp, TextID, count); 
WHILE tickcount « 11 + TimeCount DO 


MLtext(MessRec, Sp); 


Status := 2; 
FlushKeys; 
END; 
END 
ELSE IF Status = 2 THEN 
BEGIN 


(If player has not pressed return, } 
IF NOT IsDone[who] THEN 
BEGIN 
Місһаг(Тех(Кесінһо1, Key); 
(Handle the Кеу.) 
IF Key = Chr(i3) THEN 
BEGIN 
(If return, he is done.) 
NumDone :- NumDone * 1; 
IsDone[who] := true; 
IF EqualStr ingCTextRec[who]l.St, 
MessRec.St, true, false) THEN 


BEGIN 
(Handle him winning.) 
Status := 1; 


Score[who] := Score[who] + 
LENGTHCMessRec.$St); 
MLtext(MessRec, CONCATCWinStr, 
theName [who], PressStr)); 
NunToStr ingCScore [who1, Sp); 
MLtextCNameRec[who], Sp); 
FOR count := 1 TO theNum DO 
IsDone[count] := false; 
END 
ELSE IF NumDone = theNum THEN 
BEGIN (Handle no one winning.) 
Status := 1; 
MLtext(MessRec, NoOneStr); 
FOR count := 1 TO theNum DO 
IsDone[count] := false; 
END; 


END; 
END; 
END; 
SetPortCtempPort); 
END; 


(Handle Menu.) 
PROCEDURE MainMenu CtempResult : LONGINT); 
VAR 
tempInteger : integer; 
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tempStr : str255; 
BEGIN 
tempInteger := LoWord(tempResult); 
CASE HiWordCtempResult) OF 
AppleMenuID : 
IF tempInteger = 1 THEN 
DoAbout 
ELSE 
BEGIN 
GetItemCappleMenu, tempInteger, tempStr); 
tempInteger := OpenDeskAcc(tempStr); 


END; 

FileMenuID : 

IF tempInteger IN [1, 2] THEN 
BEGIN 


IF tempInteger = 2 THEN 
DoConf igure; 

IF NOT done THEN 
DoStart; 


END 
ELSE IF tempInteger = 4 THEN 
Done := true; 
EditMenuID : 
IF NOT SystemEditCtempInteger - 1) THEN 
Sysbeep( 1); 
OTHERWISE 
END; 


Н111{еМепи(й); 
END; 


(Main Event Loop.) 
PROCEDURE DoMa inLoop; 
VAR 
tempEvent : EventRecord; 
tempWindow : windowptr; 
tempCode, tempBus, tempVirtual : integer; 
tempPort : Orefptr; 
tempChar : Char; 
tempRect : rect; 
BEGIN 
REPEAT 
SystemTask; 
IF GetNextEventCeveryEvent, tempEvent) THEN 
BEGIN 
CASE tempEvent what OF 
mouseDown : 
BEGIN 
tempCode :- FindWindowCtempEvent.where, tempWindow); 
CASE tempCode OF 
inMenuBar : 
MainMenuCMenuSelectCtempEvent . where2); 


inSysWindow : 
SystemClickCtempEvent, tempWindow); 
inContent : 
IF tempWindow €? FrontWindow THEN 
SelectWindowCtempWindow); 
inDrag : 
IF (MyWindow = tempWindow) AND CtempWindow © NIL) 


BEGIN 
SetRect(tempRect, -32000, -32000, 32000, 32000); 
DragWindowCtempWindow, tempEvent.where, tempRect); 
END; 
OTHERWISE 
END; ( of tempCode case ) 
END; ( of mouseDown ) 
keydown : 
BEGIN 
CalcKeyCtempEvent.message, tempBus, tempVirtual, tempChar); 
IF BitAndCtempEvent.modif iers, cmdKey) € 0 THEN 
MainMenuCMenuKeyCtempChar 2) 
ELSE IF NotSpecKeysCtempVirtual) THEN 
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FOR tempCode := 1 TO theNum DO 


IF CtheBus[tempCode] = tempBus) AND CtheNum > 


(tempCode - 12) THEN 
DoKeyCtempCode, tempChar ) 


tempWindow := WindowPtr(CtempEvent . message); 
GetPort( tempPort); 

SetPort( tempWindow) ; 
BeginUpdate( tempW indow ); 


THEN 


DoUp ; 
EndUpdateC tempWindow ); 
SetPortCtempPort); 
END; 
OTHERWISE 
END; 
END; 
UNTIL Done; 
END; 


IF CtempWindow = MyWindow) AND CtempWindow © NIL) 


(Game over.) 
PROCEDURE DoQuit; 
VAR 
n : integer; 
BEGIN 


DeleteMenuCAppleMenuID); 
DeleteMenuCF i leMenuID); 
DeleteMenuCEdi tMenuID); 
IF MyWindow <> NIL THEN 
DisposeW indow(MyW indow); 
END; 


(Main Body} 
BEGIN 
DoSetup; 
DoAbout ; 
DoConf igure; 
IF NOT done THEN 
BEGIN 
DoStart; 
DoMainLoop; 
END; 
DoQuit; 
END. 


( MultiLine Unit by Steve Sheets 11/15/87 ) 
( Simple Edit Fields for Multible Keyboards. ) 
UNIT MultiLine; 


INTERFACE 


(Data Туре containing Text Str, Prompt Str, Cursor Cher, 
Cursor Width, Frame Rect, Frame Flag, Horizontal Start 
Position, Horizontal Current Postion, Horizontal Prompt 


Position, Vertical Start Postion.) 


YPE 
MLRec - RECORD 
St, Pr : Str255; 


Cr : char; 
CW : integer; 
Fr : rect; 


FF : boolean; 
StartH, CurH, PrH, StartV : integer; 
END; 


(Draws the Rec Edit Field) 
PROCEDURE MLupdete (Rec : MLRec); 


(Resets the Rec Edit Field, after someone has chenged a 


setting.) 
PROCEDURE MLreset (VAR Rec : MLRec); 
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(Initalize the Rec Edit Field) 
PROCEDURE MLinit CVAR Rec : MLRec; 
Prompt : str255; 


Tx : str255; 
Curs : cher; 
Box : rect; 


FrFlag : boolean); 


(Handle a Key (Printable Keys k Backspace )} 
PROCEDURE MLchar (VAR Rec : MLRec; 
С: char); 


(Reset the Text Str to S (calls MLReset).) 
PROCEDURE MLtext (VAR Rec : MLRec; 


S : str255); 
IMPLEMENTATION 
PROCEDURE MLupdate; 
VAR 
®2 : rect; 
BEGIN 
WITH Rec DO 
BEGIN 
IF FF THEN 
BEGIN 
FremeRect(Fr); 
R2.left := Fr.left + 1; 
R2.right := Fr.right - 1; 
R2.top := Fr.top + 1; 
R2.bottom := Fr.bottom - 1; 
EreseRect (R2); 
END 
ELSE 
EraseRect(Fr); 


MoveToCStartH, StartV); 

IF Pr © '^ THEN 
DrawString(Pr); 

DrawString(St); 

IF CW > 0 THEN 
DrawChar (Cr); 

END; 
END; 


PROCEDURE MLreset; 
BEGIN 


WITH Rec DO 
BEGIN 
CurH := StartH; 
IF Pr «> “” THEN 
CurH := CurH + StringWidth(Pr); 
PrH := CurH; 
IF St © '^ THEN 
CurH := CurH + StringWidth(St); 
IF Cr о” * THEN 
CW := CharwWidth(Cr) 
ELSE 


END; 
MLupdate(Rec); 
END; 


PROCEDURE ML init; 
BEGIN 
WITH Rec DO 


Рг := Prompt; 
StartH := Fr.left + 5; 
StartV := Fr.top + 16; 


FF := FrFlag; 
Cr := Curs; 
END; 
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Мігезе (Кес); 
END; 


PROCEDURE Місһаг; 
VAR 
Snall : str255; 


L : integer; 
BEGIN 
WITH Rec DO 
IF Ord(C) = 8 THEN 
BEGIN 
L := Length(St); 
IF L > 0 THEN 
BEGIN 
CurH := CurH - CharWidthCStIL 7; 
TextMode(srcBic); 
MoveToCCurH, StartV); 
DrewCharCSt (1 1); 
IF СИ > Ø THEN 
DrawChar (Cr); 
Tex tModeCsrcOr 2; 
MoveToCCurH, StartV); 
IF CW > В THEN. 
DrawChar (Cr); 
Delete(St, L, 1); 
END; 
END 
ELSE IF COrdCC) >= 32) THEN 
BEGIN 
IF CharWidth(C) + CW + CurH < Fr.right THEN 
BEGIN 
MoveToCCurH, StartV); 
IF CW > В THEN 
ВЕСІН 
TextModeCsrcBic); 
DrawCharCCr); 
TextModeCsrcOr); 
MoveToCCurH, StartV); 
END; 
DrawChar (С); 
CurH := CurH + CharWidth(C); 
IF CW > 0 THEN 
DrawChar (Cr); 
Small := ‘@’; 
$та11[1] := C; 
St := CONCATCSt, Small); 
END; 
END; 
END; 
PROCEDURE MLtext; 
BEGIN 
Rec.St := S; 
MLReset(Rec); 
END; 
END. 
TypingBattle.Rsrc 
Type MENU 
"o 
M4 


About TypingBattle... 
(- 


,2 
File 
New Game 
New Configuration 
(- 
Quit 
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9 
Edit 

Undo/Z 

(- 


Cut/X 
Copy/C 
Paste/V 
Clear 


Tgpe DITL 
, 600 
3 


button 
130 170 150 230 
OK 


staticText 
20 18 40 382 
Welcome to TypingBattle by Steve Sheets for MacTutor 


staticText 

60 18 110 382 

TypingBattle is а Multiplaying Typing Contest designed to be 
used ** 

on a Mac SE or Mac // with 1 or more ADB Keyboards. 


Туре ALRT 


,600 
40 56 210 456 
600 
4444 


Туре 5ТК8 

,601 
11 
Everyone press return to start а new sequence. 
Score: 
Ргераге to type: 
The winner is 

Everyone press return to stert a new sequence. 

No one has finished. Everyone press return to start а new 
sequence. 
TgpingBattle 
Enter your name from the correct keyboard: 
OK 
Quit 
Type STR! 

‚690 


Now is the time Гог all good men 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 

The quick red fox jumped over the lazy brown cow. 
I have not yet begun to fight. 

Ап Apple а day keeps the doctor анау. 


€ File Edit Project Run Debug 


AL 
Options File (by segment) Size 
MacPasLib 15842 
MacTraps 9440 
Segment 7. ...21286 
1214 
5800 


[R] MultiLine Source 


Тһе Visiting Developer 


David Dunham 
éa James Hopper 


Acta Reader Acta Goleta, CA 
Format Drivers Bring Freedom of Revison ppm MacTutor Vol.1 No.1 


Introduction 


Data interchange is a real problem. Everyone likes to save 
information in their own format, and no one wants to deal with 
anyone else's format (especially not to write it!). Programs like 
the original version of Acta, David's desk accessory outline 
processor, support only limited file format interchange, usually 
viaa separate translator program. Such translation programs are 
very inconvenient, but there are reasons for writing them. First, 
the extra code required to read additional file formats can 
significantly enlarge a program while adding support for formats 
which most users never need. It's better to separate this code 
from the more commonly-used parts of the program. Also, the 
intermediate file is necessary because many programs don't use 
the public clipboard (desk scrap) for formatted text. Second, 
many of these formats are considered proprietary and are not 
generally available, for example Microsoft Word 1.05. Finally, 
there are a lot of file formats out there — most of us are simply 
too lazy to cover all of them. 

Many people work with a variety of editors, word proces- 
sors, and desk accessories, and need the ability to exchange files 
between them. Separate translation programs such as the one 
used with WriteNow are simply too inconvenient. Macintosh 
users have grown accustomed to (and deserve) a higher degree of 
integration between programs. One way this can be done is to 
‘teach’ the program what the data must look like by having the 
program look-up the format externally to itself. In this way, the 
program does not have to be revised to read or write a new format 
whenever someone releases a hot new product. In this article, we 
will discuss an example of such a technique used in Acta 2.0, that 
can be applied to other developer's software projects to ease the 
burden of being compatible. [Tt is hoped this article will spur 
someone to write a similar article on how Pagemaker compati- 
bility can be achieved by new word processors without having to 
wait for Aldus to release a new Pagemaker version. Wouldn' t it 
be neat if the word processor or graphics developer could make 
his product Pagemaker compatible without Aldus having to do 
anything? -Ed] 

Acta 2.0 handles additional data formats with format driv- 
ers, files which, like printer drivers, reside in the system folder. 
Because they're separate from the main program, users can 
install only the formats required by dragging these driver files to 
the system folder. As new word processors come out, the new file 
formats can be supported with new format drivers, rather than a 
new version of Acta. Given the file format documentation for the 
new word processing program, drivers to support new formats 
can be produced by third party programmers such as Jim. 

David will first explain format drivers using C as the target 
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language. Jim will then discuss a simple input format driver in 
Pascal, focusing on the glue required to link functions written in 
C to units written in Pascal. Although this article deals with 
format drivers as implemented in Acta, the concept of format 
drivers can be adopted in most programs. 

Additional technical information on Acta can be found in a 
short document describing the format of Acta files, available 
from online services such as Delphi or CompuServe, or from 
Symmetry Corp. For convenience, it is included at the end of this 
article. This information would be useful if you're implementing 
your own Acta format driver, but you won't need it to read this 
article. 


Input Drivers 

Acta supports two kinds of format drivers: input and output. 
A file can contain resources for both, but we'll start by looking 
at input drivers. An input driver's job is to read a file, parse the 
data, and pass it to Acta as topics (Acta's smallest data object). 
Acta handles everything else, which keeps down the overhead in 
each format driver. We'll use the input driver а TEXT as ап 
example format driver. This example was written in C and 
compiled using MPW C. This driver reads text files, splitting the 
text into topics at return characters. 

The driver a TEXT is composed of a variety of resources 
stored in the resource fork of the filea TEXT. The file type for 
a format driver is ‘ACTF,’ which is how Acta recognizes it as a 
format driver. The file creator “Atxt’ associates a unique icon 
with the driver file in the Finder using the usual additional 
(bundle) resources. We discuss other resources in the following 
paragraphs. 


oN 
[e 
“-/ 
ACTf — Тһе code for the driver is stored as a resource of 


type ACTf. It's actually a standard code resource which Acta 
loads using GetResource. 

ICN# — An input driver file must contain an ICN# 64 
resource which, along with the file name, identifies a particular 
format driver. The user selects an input driver from a scrolling 
icon list (see Appendix) as part of Acta's Open... dialog (see 
illustration below). To avoid confusion with application names, 
format driver files start with “а ” by convention; however, this 
prefix is not displayed in the scrolling icon list. 

FILT — If a resource FILT 64 is present, it's assumed to be 
a code resource containing a file filter function, defined as in 
SFGetFile: 
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D Application Notes 
Г) betaTesters 

Г) bmugDemo 

D bugs 

© examples 

D extensibility 

D format drivers 

D jpiDemo 

D laundry 


Document 
Format: 


pascal short fileFilter(pb) ParmBlkPtr pb; 


The driver author provides this filter so Acta can open 
multiple file types using the format driver. 

TYPE — If there is no FILT 64, Acta determines which files 
to open by examining the input driver’s resource TYPE 64, which 
is four ASCII characters and specifies a single file type to be con- 
verted. 

Once the user decides to open a file, Acta calls the driver, 
assuming it's a C routine defined as is read text() in Listing 1. 


/* 

Read TEXT documents into Acta 

Written by Devid Dunham 

91987 Maitreya Design - code may be freely used 
in Acta format drivers 

% 


typedef int word; /* Synonyms for VAX-hackers */ 
typedef unsigned char byte; 


"define TAB "NU" 
def ine CR М? 


def ine NIL (OL) 
define TRUE (-1) 
"define FALSE Ø 


"define TEXTtype 1 
"define PICTtype 2 


struct BLOCK_ATT ( /* Attribute portion of a topic */ 
word  bType; /* TEXTtype, PICTtype, .. */ 
word bAttributes; /* 0 */ 
word  bFont; 
word  bStyle; 
word bSize; 


byte  bColor; /*Triangle color: index to COLS 
resource, 0 - black */ 
byte filler; /* 0 */ 


byte  firstLine; X /* Show first line only? OxFF or 0 */ 

byte expanded; /* Subtopics visible? OxFF ог 0 */ 

word hidden; /* Is block hidden (Бу Collapse)? count 
of hide depth */ 


); 
typedef struct BLOCK.ATT — BLOCK АТТ; 


/х 

READ_TEXT - Read generic TEXT file to Acta outline 
infil : refNum of input file 
resf il : refNum of input file’s resource fork 
ett : default topic attributes 
edd topic : pointer to routine to call 

47 
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OSErr read textCinfil,resfil,att,add topic) 
word infil, resfil; BLOCK АТТ *att; ProcPtr add topic; ( 


register char *Xtext; /* Handle for text */ 
register OSErr еггог; 

long count; /* Used in FS calls */ 
register word level; /* Topic’s level */ 
word i_count, last.count, spaces; 

word last level; /* Level of previous topic */ 
word — Space. indent; /* No. of spaces = to а tab */ 
cher с; 

long size; /* Length of text */ 

Handle h; 


word  oldResFile; 


oldResFile = CurResFile(); /* Previous top resource 
file */ 
UseResF ile(Cresf il); /* Just look in document */ 
h = Get IndResource( ‘EFNT’, 10; 
/* MDS Edit/QUED/miniWRITER 
font */ 
if (h != NIL) ( /* There is such a resource */ 
att->bSize = **(word **)h; 
GetFNum(*(char **)h + 2,katt->bFont); 


UseResFile(oldResFile); /* Restore search order */ 
level = -1; /* We've never parsed a topic */ 
lest level = Ø; 
space .indent = 5;/* SHOULD be rsrc; 5 Гог MORE 1.0 */ 
last_count = i count = spaces = 0; 
text = NIL; 
att bTgpe 


- TEXTtype; /* Everything is text! */ 
while CTRUE) ( 


/* Keep going until EOF */ 
/* Will this die with empty file? */ 
count = IL; /* Read а single character */ 
error = FSRead( infil, &count, &c); 
if Cerror) ( /* Probably hit EOF before RETURN */ 
if (error == eofErr) return(noErr); 
/* Finished with the file */ 


returnCerror ); /* Uh-oh... */ 
if (с == TAB) ( 
i-count**; /* Increment indent count */ 
Speces - 0; /* Start count over */ 
) else if (с == * “) ( 
Spacest*; 
if (spaces == space indent) ( /* А pseudo-tab */ 
i-count**; /* Increment indent count */ 
spaces = 0: /* Stert count over */ 
) else ( /* Not space or tab */ 
if (level == -1) /* Very first topic */ 
level = 1; 
else 


level = level + i.count - lest count; 
if Clevel ‹ 1) 

level = 1; /* Minimum indent */ 
if Clevel › lest level + 1) 

level = lest level + 1; /*go one level deeper */ 
if (level == D ( /* Left-margin topic? */ 

att->expanded = TRUE; 

att hidden = 0; 

) else ( /* Subtopics aren't expanded */ 
att-»expanded = FALSE; 
ett- hidden = level - 2; 
/* ® of collapsed levels above */ 


) 
text = NIL; /* No text so far */ 
/* Read until end of line or end of file */ 
while (с != CR && error == noErr) ( 
if (text == NIL) ( /* First character? */ 
text = NewHandleC 1L); 
**text = c; /* Copy it in */ 
) else 
PtrAndHand(&c, text, 1L); /* Add to the end */ 
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count 
error 


IL; /* Read a single character */ 
FSRead( inf i1, &count, іс); 


if Cerror != noErr && error != eofErr) 
returnCerror ); /* Uh-oh... */ 

if Ctext == NIL) ( /* Empty topic */ 
(*add_topic)CNIL,@L, level, att, NIL); 


} else ( 
size = GetHandleSize( text); 
HLock( text); /* Keep dereference valid */ 


(*add_topic)(*text, size, level, att, NIL); 
DisposHandleCtext); /* Free the memory */ 
text = NIL; /* Mark it as empty */ 


if (error == eofErr) ( 
return(noErr ); /* Finished with the file */ 
last_count = i_count; 
i-count = spaces = 0; 
last_level = level; 
) /* end if */ 
) /* end while */ 


/* input file’s indent */ 


/* Remember topic’s level */ 


«listing 1» 


The actual code in our example is straightforward. First, it 
looks in the resource fork for the EFNT resource (where MDS 
Edit, QUED, and miniWRITER save a text file's font and size). 
Then it reads the data fork a character at a time, appending them 
to the end of a block of memory until it reaches either the end of 
the file or a return character. When this happens, it calls 
add topic, a routine in one of Acta's code resources. If there are 
any errors, it just returns the error to Acta, which takes care of 
informing the user. А driver can display its own error messag- 
es, in which case it returns -2048. 

Add topic inserts the data into Ас/а 5 family tree structure. 
It's declared as: 


/* 
ADD_TOPIC - Create а new topic and link it in 
data : topic data 
Теп : length of deta 
level : level of topic (1 = left margin) 
attributes: topic’s attributes 
stuleHandle : RESERVED 
*/ 


void add_topicCdata, length, level, attributes, styleHandle) 
Ptr data; long length; word level; BLOCK *attributes; Handle 
styleHandle; 


The code is compiled into the resource АСТЕ 64: 


c a_TEXT.c 

link -rt АСТҒ-64 -sn Main=a_TEXT -c Atxt -t АСТЕ д 
а_ТЕХТ.с.о -o d20:MPW:a- TEXT д 
* (Libreries) ^Interface.o д 
* (CLibreries)"CInterface.o 


Listing 2 summarizes the resources which make up an input 
driver, in REZ format: 


resource 'BNDL^ С 128) ( 
Ах’, 


0 
( /* array TypeArray: 2 elements */ 
' ION ’ 


( /* array IDArray: 1 elements */ 
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0, 128 

); 

‘FREF’, 

( /* array IDArray: 1 elements */ 
0, 128 


) 
); 


resource ‘FREF’ (128, “а TEXT^) ( 
‘ACTF’, 
0, 


); 
data 'Atxt^ (Ø, purgeable) ( 
“01987 Maitreya Design 23 January 1987” 


data ‘TYPE’ (64, purgeable) ( 
‘TEXT’ 


); 
and the ICN# 
«listing 2 — Rez input» 


Output Drivers 

An output driver is responsible for taking the data from an 
Acta topic and writing it toa file. Again, Acta handles most of the 
overhead, but the process is slightly more complicated, because 
most word processor formats involve tables and pointers. Acta 
calls the output driver before passing any topic data, once for 
each topic, and again after all the data. The driver generally 
builds any tables during the first and last call. For example, a 
word processor format may begin with a list of paragraphs 
(conveniently written during the first call) and end with a pointer 
to free space (best written after all the topics have been output). 

The example output driver is a RTF, which converts an 
outline to Rich Text Format, Microsoft's interchange format. It 
creates a file which is as true as possible to the screen appearance 
of the Acta outline. (The КТЕ specification is available from 
Microsoft. It's beyond the scope of this article to explain in 
detail, but it's a format for representing formatting information 
using only the standard 7-bit printing ASCII characters. Back- 
slashes precede formatting words, and braces group items. This 
format is also used for Microsoft's MSDOS word processor.) 


ОУ 
м 
VA 


ACTf — The actual code for the output driver is in the ACTf 
0 resource and is loaded by Acta using GetResource. 

ICN# — An output driver file must contain an ICN# 0 
resource which, along with the file name, identifies the format 
driver to the user. The user selects an output driver from a 
scrolling icon list (see Appendix) as part of Acta’s Save as... 
dialog (see illustration below). When the userclicks on this icon, 
Acta highlights the ruler and label buttons depending on the 
RULR 0 resource. 

RULR — This is a word, in which the following bits have 
meaning: 

0х8000 format has rulers 
0х4000 format doesn't use labels 
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As usual, don't set unused bits. resource, 0 = black */ 


byte filler; /* 0 */ 

TYPE and CREA — Theresources TYPE and CREA Oare byte  firstLine; /% Show first line only? ØxFF or Ø */ 
OSTypes, 4 ASCII characters Acta uses to set the output file's byte expanded; /* Subtopics visible? OxFF or Ø */ 
type and creator. word hidden; /* Is block hidden (Бу Collapse)? count 

Acta passes a pointer to a parameter block which indicates of hide depth */ 


I : | I ); 
the topic's level, data, attributes, label, and other information; | typedef struct BLOCK ATT BLOCK_ATT; 
this is defined in Listing 3. 


When the example driver gets ће -1 message (indicating the | Struct OUT-PARMS ( 


word fRef ; /* Data fork refNum */ 
word rRef ; /* Resource fork refNum */ 
© 620 word message; 
С data <-> byEktensi... word level; 
Biles TRA m word n; /* Торіс”5 absolute number */ 
і style shee x сһаг *data; 
5... 2 long len; /* Length of data */ 
; Document Format BLOCK АТТ ха; 
Seve outline аз: Q THPrint print.rec; 
| word already. error; 
char *label; 
word label Type; 
word *raw_label ; 
word rulers; 
Sis = pet word error_reporting; /* not used */ 
. R. B. 1. Handle reserved; /* Currently NIL */ 
Onorulers rue] word last. level; 
word private; 
; 


initial call), it writes the RTF header, including the name of every | typedef struct OUT.PARMS — *P.PTR; 
installed font. When it gets the O message (indicating a topic's | 
data), it outputs the topic's style, ruler, label, and data. If it | /* Function prototypes */ 


А t : void file_error(); 
encounters an error, it must return the error (or -2048 ifitdoesn’t | yoig 00; 
want Acta to put up an error dialog). Sinceacoderesourcecan't | void w-bute(); 
have globals, it sets already_error in the parameter block. ый та e 
A КТЕ ignores the +1 message, which follows all the 0 mes- , 
sages. /* 
МКІТЕ. ЕТЕ - Write Rich Text Format document 
* 
/* : : А 
Outputs Acta outline as Rich Text Format (Word 3.x) document val write RIFCp) ped ister P-PTR p; ( 
Written by David Dunham | or 5; Т 
91987 Maitreya Design - code may be freely used d де 
г Acta format drivers Handle handle; 
register word i; 
typedef int word; /* Synonyms for VAX-hackers */ s. e ci rsrc-fonts; 
typedef unsigned char byte; WindowPtr front: 
#def ine TAB М | 
i TOY switch (p- message) ( 
"def ine CR \г pond | 
; wstr(p, “\P(\\rtf\\mac”); 
eee eee 5 /® Output font table Cevery installed font) */ 
"def ine FALSE б w-strCp, “\Р (NV onttb1”); 
rsrc-fonts = quU T T 
for (i = 1; i <= rsrc_fonts; 1++) 
x x ғ 
в SetResLoad(FALSE); /% Don't actually load fonts! */ 
"define DECIMAL 11 handle = GetIndResource( ‘FONT’, 1); 
def ine ROMAN 12 GetResInfoChandle, &id, &count , &name ); 
define BULLETS 14 SetResLoad( TRUE); /* Back to normal */ 
ыы if (name. length != 0) ( 
w-Str(p, “\P\\f%); 
define TERT | NunToStr ingCClong?id >> 7,&string); 
| w_str(p, &string); 
"def ine PICTtype 2 ео a е); ; 
‘struct BLOCK. ATT ( — /* Attribute portion of a topic %/ Т. 
word  bType; /* TEXTtype, PICTtype, .. */ шер, ; 5 
word  bAttributes; /* Ø */ 
dol с. w-Str(p, P) Ar^); 
word  bSize; 2. 
byte  bColor; /* Triangle color: index to COLS ' 


© The Definitive MacTutor, Vol. 4 267 


w-Str(p, ^P (NNsT18NVf 2); register char с; 
NumToStr ingCClong)?p-?»att-?bFont , &str ing); 


w-str(p,&string); if (p already error) return; /* Already have error */ 
w-Str(p, ^PNfs^); for Ci = 0; i < len; i++) ( 
NunToString(Clong)p att bSize << 1,kstring); с = %5++; 
w_str(p, &string); switch (c) { 
if (p^ att bStyle & bold) ( сазе '(': 
w-StrCp, PN b^); case ')': 
) case 44”: 
if (p att—bStyle & italic) ( w-byteCp, 4720; w-byte(p,c2; 
wstr(p, *\Р\\1*); break; 
) case CR: 
if (p-»att-»bStyle & underline) ( wstr(p,“\P\\line “); 
и_${г(р, “\P\\ulw’); break; 
) case TAB: 
if (patte bStyle & outline) ( и_$4г(р, *\Р\\4аь 4); 
w-StrCp, “\Р\\оиї1*); break; 
default: 
/* Output ruler stuff */ w_byte(p,c); 
if (p-> level > 1 && p-?labelType == DECIMAL) ) 
1 = 48; } 
else ) 
1 = 32; 
if (p-?lebelTgpe == BULLETS) i = 16; /* 
if Ср-> 1абе1Туре == NONE) i = Ø; W_BYTE 
/* Output first indent and left indent іп twips (1/20 x/ 
point) */ void wbyte(p,b) P_PTR p; unsigned char b; ( 
и_$4г(р, “\Р\\11*); long count; 
NumToStr ing(Clong)(p-> level * 16 + 1) х 20,&string); register OSErr error; 
w_str(p,&string); 
wstr(p, “\P\\f i"); if (p-»already_error) return; /* Already have error */ 
NumToString(Clong)i ж -20,&string); count = sizeof (char); 
wstr(p, &string); error = FSWriteCp-»fRef , &count, &b); 
w-byte(p,^ ^);  /* Be sure not to run into text */ if Cerror) ( 
/* Output label */ file_errorCerror,p); 
if С(р->Таре12101 != Ø) ( return; 
for Ci = 1; i <= р-Лабе1101; i++) ) 
) w-byteCp,p- label[il); ) 
if Cp-»att-»bType == PICTtype) ( /* 
w-StrCp, “\P{\\pict\\macpict\\bin”); W.STR - Write а Pascal string 
NunToStr ingCClong2p-? len, &str ing); x/ 
w-StrCp, &string); void w_str(p,s) P_PTR p; char si]; ( 
w-byte(p,^ '5; long count; 
count = p-?len; register 05Егг error; 
error = FSWriteCp-»fRef ,&count, р-> data); 
wbyte(p, ^) ; if (p-»already_error) return; /* Already have error */ 
) else ( /* Not a PICT */ count = 610); 
warp(p,p-? len,p-? data); error = FSWriteCp fRef , &count, &s[ 1); 
if (error) ( 
w-StrCp, PA par) N92; f ile еггогСеггог,р); 
break; return; 
cese 1: 
wstr(p, ^P)Ar 5; ) 
break; «listing 3» 


return(Cp-? already. error); M . T | 
Listing 4 summarizes the additional resources which make 


up an output driver. 


[* 'BNDL^ (128) 
FILE.ERROR - Display the appropriate message for a file error iiu 
*/ , 7 
void fileerrorCerror,p) register OSErr error; P.PTR р; ( ( /* array TypeArray: 2 elements */ 
* [1] * 
if Ср-› а1геаду_еггог != noErr) return;  /* Only once */ Аз. / 
р-›а1геаду-еггог = error; /* Indicate error */ {  /* array IDArray: 1 elements */ 
/* [1] */ 
0, 128 
/* ); 
WARP - Escape {,\,},CR, TAB /* (2) */ 
|. l 'FREF ^, 
void warp(p, len,s) P_PTR p; long len; register char *s; ( (  /* array IDArray: 1 elements */ 
long count; /* [1] */ 
register word i; 0, 128 
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) 
); 


resource ‘FREF’ (128, “a_TEXT”) ( 
‘ACTF’, 
0, 


wa 


); 


data “ТҮРЕ” (0, purgeable) ( 
p dm 


data ‘CREA’ (Ø, purgeable) ( 
“ММО ^ 
b 


data 'RULR^ (0, purgeable) ( 
%%0000" 
; 
data ‘Artf’ (Ø, purgeable) ( /* Signature */ 
“01987 Maitreya Design 11 March 1087” 


and the ICN#s 
«listing 4 — Rez input» 


Doing it with Pascal 

It’s alittle known fact that Acta makes a superior Scrapbook. 
The example in this section is a relatively simple input format 
driver (in Lightspeed Pascal [LSP]) which reads a scrapbook file 
into an Acta outline, converting each text block and picture in the 
scrapbook to a separate topic. With this driver, those of you with 
a lot invested in scrapbooks can painlessly convert to Acta. 

Unfortunately (for Pascal programmers) Acta assumes its 
format drivers are C functions. This is because Acta is written in 
C, and because David takes a perverse pleasure in making Pascal 
programmers read C declarations. (The authors of Inside Macin- 
tosh no doubt have a similar feeling.) But some Pascal compilers 
won't generate code that can call or be called by code written in 
C. This section will discuss a relatively general method of 
coercing a standard Pascal compiler to generate code compatible 
with C. Note that MPW Pascal allows you to declare procedures 
as C functions so they can talk directly to Acta. 


Linking Code Produced by Different Compilers 

Except for a few systems like MPW, it's not possible to link 
code compiled by different compilers. On the Macintosh, one 
way to overcome this is to compile code into code resources. 
These can then be loaded using the segment loader, or in the case 
of a DA such as Acta, with GetResource. Using this method it's 
possible to separately compile and link blocks of code totally 
independent of which compiler generated them, using virtually 
any compiler desired by the programmer. 


Argument Order 
In both C (atleast Aztec C,in which Acta is written; MPW C, 
used in the examples; and LightspeedC, another compiler we're 
familiar with) and Pascal, arguments are passed to procedures on 
the stack. However the order in which the arguments are pushed 
onto the stack is different for the two languages. Pascal pushes 
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arguments onto the stack in the order in which they are declared. 
C pushes the arguments in the reverse order of declaration. (Note 
that this allows C routines to have a variable number of argu- 
ments; the first argument is always in a known place [the top of 
the stack] and can indicate how many other arguments there are.) 

If a Pascal procedure is to be callable from C, it must declare 
its arguments reversed from the C function call, for example: 

The C declaration for the format driver main procedure 
read Scrap is: 


OSErr read ScrepCinf il,resfil,att,add topic) 
word infil, resfil; BLOCK. АТТ *att; ProcPtr add topic; 


while the Pascal declaration is: 
Function read. ScrepCedd topic:ProcPtr; att:Block Att; 
resfil,infil:Integer) : OSErr; 


When calling a C function from Pascal the arguments must 
be passed in the reverse order from the C function declaration, for 
example: 

If the C declaration for add topic is: 


void add_topic(data, length, level ,attributes, styleHandle) 
Ptr data; long length; word level; BLOCK *attributes; Handle 


styleHandle; 


the Pascal call to the function add_topic is: 
add_topic(Nil,att, level, size, text); 


while the C call is: 
(*add_topic)(*text,size, level, att, NIL); 


Argument Passing 

C allows a variable number of arguments to be passed to a 
function, so the function can’t simply remove a fixed number of 
bytes from the stack before returning as is done in Pascal. When 
aC function calls a Pascal procedure (Acta calls thea, Scrap main 
procedure) this creates problems as both the Pascal procedure 
and the calling C function will remove the arguments from the 
stack. The converse problem occurs when a Pascal procedure 
calls a C function (a Scrap calls add topic) — no one removes 
the arguments from the stack. 

For some Macintosh Pascal compilers (Lightspeed and 
TML) this problem can only be solved by resorting to assembly 
language “glue” routines. Those of you who don't care for 
assembly code please just hold your nose and read on. The result 
of this discussion is two small, relatively general assembly 
procedures. One procedure lets Acta call an input format driver 
written in Pascal and the other allows a Pascal driver to call Acta's 
add topic procedure. You won't have to write any assembly 
language to add your own input format driver (well, as long as the 
format driver interface doesn't change anyway), though output 
format drivers are left as an exercise for the reader (or a future 
column)! 

Calling a Pascal procedure from C involves declaring the 
Pascal procedure as having no arguments, and copying the 
arguments from the stack into local variables using an assembly 
procedure (Listing 5). By doing this Pascal will not mess with the 
stack by deleting the arguments. This is one of those areas where 
languages like C have it all over Pascal, which was designed to 
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keep the programmer as far from the machine as possible. This 
promotes machine independence, but like most blessings ex- 
tracts a price. When you absolutely must get down to the bare 
metal of the machine, you're forced to use assembly language to 
do it. 


; Procedure GetArguments(C VAR add.topic.Ptr : ProcPtr; 
р VAR ett : Topic. Attributes; 

4 VAR ResRefNum : Integer; 

р VAR Refnum : Integer); 


This procedure will pull the arguments passed to input 
routines from the stack and put them in the input routines 
interna! veriebles. This procedure will not change the stack 
from what C expects on return from the input routine. 


This procedure is called аз the first statement in the input 
module. it assumes that Аб was linked at the beginning of the 


code module. this occurs if there аге anu local variables at 
the top level of the code module main entry point routine. 


Stack looks like this: 


input paremeters to input module from Acta 


Return Address 


019 Аб 


~ we We o o We We 


; Аб=== 


arguments Гог GetArguments 
GetArguments calling procedure return address 


;Mss2» Old Ад (2222 SP 
; 
; 
9 
link Аб, 86 
nove.L A2,-CSP) ; Seve А2 
move.L 8(Аб),А1 ; M = ptr to RefNum 
nove.W 8(Аб),(А1); move refnum from c frame to pascal frame 
nove.L 12(А0),А1 ; Al = Ptr to ResRef Num 
move.W 10САб ), CA1) move ResRefNum from с to pascal frame 
move.L 16(А0),А1 Al = Ptr to ATT 
move.L 12(А6),А2 A2 = ptr to C ATT 
move.L СА2 )+, СА1)+ move С АТТ to pascal АТТ 
move.L СА2 )+, СА 1)+ 
move.L СА2 )+, СА1)+ 
move.L СА2 )+, СА 1)+ 
nove.L 20СА0),А1 А1 = ptr to Раѕса1 Procptr 
move.L 16(Аб), CA1) move procptr from с to pascal 
nove.L (SP)+,A2 ; restore А2 


; M points to getarguments stack frame 


"- о We Ce 


we We 


опік А 
rts 
«listing 5» 


Function Results 

Pascal allocates space on the stack for the functional result 
and places the arguments on the stack. When the function returns 
the result is on top of the stack. A function written in C returns 
the functional value inregister DO. Acta (a program) calls input 
format drivers as functions. A format driver written in Pascal 
must conform to this standard for passing functional results. 

A Pascal format driver must be defined as a procedure so it 
doesn't try to write its function result to the stack. An assembly 
language procedure is called as the driver's last statement to load 
the functional result into register DO (Listing 6). 
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; Procedure CFunctionReturn(Error : OsErr 2; 


М 


This procedure is а kludge to allow С end Pascal routines to 
work together Acta calls the a Text Main routine and expects 
its functional value to be in the register 00, however Pascal 
expects there to be space reserved on the stack for it, and 
would save it there if allowed. This procedure takes an 
argument which would normally be set equal to the functional 
result апа puts it in 00. The calling procedure will then not 
set the function equal to this value. 


move.L (SP)+, Ад 

move .W CSP2*,DO 

jmp (Ag) 
«listing 6» 


; Get Return address 
; put functional result in 00 for С 


; RTS 


Calling a Procedure Passed as an Argument 
Acta passes the address of add_topic as an argument to the 
input module. Unfortunately Pascal can’t call a procedure by 
pointer directly. The solution, once again, is an assembly glue 
routine to take this procedure address as an argument and jump 
to the procedure (Listing 7). 


; add_topic(text: Ptr;size: LongInt; level: Integer ; 
; att:TopicAttributes; add_topic_Ptr :ProcPtr); 


) 


This procedure is the glue routine between pascal call to 

edd topic and Acta’s add topic routine. Pascal can not call а 
procedure by using the procptr so а ASM glue routine is 
required. In addition C requires the calling routine to take 
its own erguments off the stack. The procptr was added to the 
edd.topic argument list on the end so that this routine could 
easily pull it off and be left with the arguments on the stack 
as C wants to see them. This procedure must then remove the 
arguments off the stack аз the C procedure will not do it. 


edd topic 
lea . SeveReturn, Að 
nove.L (SP)+, CAQ) 
move.L (SP2*,A0 


; save return | 

; get subroutine address 

jsr (А0) ; JSR to С edd topic routine 
lea 18(SP),SP ; pull arguments off stack 
lea SaveReturn,A0 ; restore return address 
move.L (A0),-(SP) 


rts 
SaveReturnDC.L Ø ; storage for return address 
«listing 7» 


Putting it All Together іп Pascal 

Listing 8 is a shell which can be called from Acta. A call to 
the user's input driver is inserted in this shell. The user's format 
driver code is stored in a separate unit and a uses clause which 
references it is added to the shell replacing the Scrapbook Uses. 
The assembly language procedures are contained in a file called 
ASM LIB Library which is compiled using Consulair's Assem- 
bly Development System (formerly MDS) and converted into an 
LSP library using REL Convert. This library must be added to the 
project in build order before the format driver code (see figure). 
See the LSP manual for more information on how to build a code 


resource. 
UNIT InputDriverShel1; 
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INTERFACE 
USES 
Globals, Scrapbook; 


( main entry point for the code unit ) 


Refnum : Integer) : 0$Егг; 


IMPLEMENTATION 
FUNCTION а. 5сгарВоок; 


PROCEDURE Main; CONST 
ActaTextTopic = 1; 
IMPLEMENTATION ActaPictTopic = 2; 
Торісіеуе11 = 1; 
PROCEDURE Main; TopicLevel2 = 2; 
VAR VAR 
anErr : OsErr; ResHandle : Handle; 
add. topic. Ptr : ProcPtr; TempPtr : Ptr; 
att : Topic. Attributes; enErr : 05Егг; 
ResRefNum : Integer; ErrorString : Str255; 
Refnum : Integer; RError : Integer; 


AppResNumber : Integer; 
( def for ASM C/Pescal glue for Acta input format driver ) ResCount : Integer; 
PROCEDURE CFunctionReturn CanErr : OsErr); external; Size : LongInt; 
PROCEDURE GetArguments (VAR add_topicPtr : ProcPtr; ТТуре : 05Туре; 
VAR att : Торіс Attributes; i, j, k : Integer; 
VAR ResRefNum : Integer; 


VAR Refnum : Integer); External; ( Acta internal procedure for adding а topic to the active 
window. This procedure was written in C, so arguments must be 
BEGIN put on the stack in the reverse order of Dave's documentation. 
This procedure is really linked to әп ASM glue routine which 
pulls the pointer to the add. topic procedure off the stack and 
jumps to it and pulls the arguments off the stack before 
returning as well ) 


( get the funtion arguments from the stack, 
behind compiler's back ) 
GetArgumentsCadd_topic_Ptr, att, ResRefNum, Refnum); 


( call the specific input format driver ) 


PROCEDURE add_topic Cempty : Ptr; 
anErr := a.ScrepBook(add topic Ptr, att, 


att : Topic. Attributes; 


ResRefNum, Refnum); level : Integer; 
size : LongInt; 
( put: the functional result in register бә so text : Ptr; 


Acta can get it } 


add_topic_Ptr : ProcPtr);external; 
CFunctionReturnCanErr); 


END; PROCEDURE Init; 
END. 
«listing 8» ( initialize а. 5сгарроок  ) 


VAR 
Watch : CursHandle; 


=== a Scrapbook.Proj 


Options File (bu build order) Size 
BEGIN 


D A PasLib 8072 

MacTraps 5440 Watch := GetCursor(WatchCursor ); 

ASM LIB Library 84 ( change cursor to watch while converting file } 
DNVR globals.pas 0 SetCursor (Watch**); 
D МУ К Scrapbook.Pas 556 ( save away the current resource file ) 
ОМУ R_sInput Format Drive... 66 AppResNumber := CurResFile; 


( Read from the input file ) 


Finally, here's the actual source code which converts UseResF i leCResRef Num); 


TEXT and PICT resources in a scrapbook file (actually, in any 


resource file) into Acta topics. ( stert out with the text blocks ) 


ATT.bType := ActaTextTopic; 
ТТуре := ‘TEXT’; 
END; ( Init ) 


BEGIN ( a_Scrapbook ) 


UNIT Screpbook; 
( this unit will read а scrapbook file into a set of Acta 
topics for use with Acta 2.0 or higher ) 


INTERFACE 
Init; ( Initialize ) 


S 
Globals; ( Pascal def of Topic Attributes record ) FOR j := 1 TO 2 DO 
E 


FUNCTION a_ScrapBook Cadd_topic_Ptr : ProcPtr; 
ett : Topic_Attributes; 
ResRefNum : Integer; 
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( if the current output type is text then count TEXT ) 
( resource, else count number of picture resources ) 
ResCount := CountResources(TType); 
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КЕггог :- КезЕггог; 
ІҒ БЕггог - поЕгг ТНЕМ 
BEGIN 
( loop through all resources of current type ) 


FOR i := 1 TO ResCount 00 
BEGIN 
ResHandle := GetIndResource(TType, i); 


RError := ResError; 
( convert only resources actually in 
the scrapbook file } 
IF CRError = noerr) AND (HomeResF ile( 
ResHandle) = ResRefNum) THEN 
BEGIN 
HlockCResHandle?; 
Size := LongintCGetHandleSizeCResHandle22; 
ада topicC(NIL, АТТ, Торісіеуе12, Size, 
ResHandle*, add_topic-ptr); 
HUnLock(ResHandle ); 
END; ( If (RError =...) 
Re leaseResource(ResHandle); 
END; ( For Crescount) 
END; ( RError) 
ATT.bType := ActaPictTopic; 
ТТуре := ‘PICT’; 
END; (for (1 to 2) } 
( Use the application resource fork } 
UseResF i leCAppResNumber ); 
InitCursor; ( initialize cursor ) 
( somewhat simplistic error reporting ) 
а.5сгарВоок := КЕггог; 
END; ( а.5сгарВоок ) 
END. ( 5сгарВоок ) 
«listing 9» 


Conclusion 

Format drivers allow programs to be extended easily, adding 
new features without an entirely new program. They also allow 
the user to customize the program's features. On the implemen- 
tation side, they are easy to write and allow packages to be written 
in multiple languages, even with development systems that do 
not normally support this. 

Extensibility need not be limited to handling file formats. 
Future versions of Acta may have feature drivers. 

The shrewd reader will have noticed that the techniques 
we've discussed allow you to break up your program into pieces 
which can be sold separately. This means you can get the 
program out the door quicker, and add the features later. And 
your marketing experts can have a field day packaging the 
different pieces. 


Exercises 
The answers to these exercises will not appear in next 
month's MacTutor. But, you may be able to release them as free 
or shareware programs. 


1.Modify a TEXT to support MPW's font and size 
specification. 


2. Write an input driver which reads a tab (or comma) 
delimited file, creating a new level at each delimiter. 
(This format driver should have a name such as 
a TEXT/tab, so the user has the choice of how to split 
topics.) 
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3. Write an input driver which reads a text file into a 
single topic. Acta uses TextEdit, so check for files 
which are too large. (This format driver should have 
a name such as a TEXT/1 topic, so the user has the 
choice of how to split topics.) 


4. Adopt the format driver technique in your own pro- 
gram. 


5. (extracredit) Write a format driver for Microsoft Word 
3.0 format. 


Appendix — Scrolling Icon List 

Implementing the user interface really isn't in the scope of 
this article, but we haven't seen many examples of custom list 
definition functions (LDEFs). 

Adding a scrolling list to the Standard File dialogs is pretty 
easy. Custom (SFPGetFile/ SFPPutFile) dialogs have a us- 
erItem, and the List Manager handles the work (with the aid of a 
custom LDEF). The dlgHook initializes the list when it gets 
passed item -1, and the filterProc checks for mouseDown events 
in the list. The only tricky part is in disposing of the list after the 
SFPPutFile call. If you call LDispose after the call, the List 
Manager tries to call DisposControl for the scroll bar...but 
DisposDialog has already disposed of all the controls. If you try 
to call LDispose in the dlgHook after a click on the OK button, 
you're faced with the problem that the dialog may not really go 
away — the user may decide not to replace a file with the same 
name. Our solution was to set the list’s vScroll field to NIL before 
calling LDispose, since after the return from SFPPutFile, the 
control no longer exists. 

Flying in the face of Inside Macintosh volume IV, the LDEF 
is written іп С. The routine presented here shows only how to 
draw labelled icons (Acta’s LDEF uses additional data struc- 
tures, and disposes them when it receives an ICloseMsg). 


struct ListEntry ( 
Handle icon; 
char пате [64]; /* Icon label (file name) */ 


); 
typedef struct ListEntry | ListEntry; 


/* 

LDEF - List Definition Procedure 

%/ 

pascal void 

ldef (message, select,rect,cell,data0ffset,dateLen,handle) 
word message; 


word select; 

Rect *rect; 

Cell cell; 

word dataO0ffset ; 

word dataLen; 

ss handle; 
Rect box; 
ListEntrulistData; 
BitMap iconBits; 
GrafPtr thePort; 
сһаг disp layName [64]; 


if (dataLen == Ø) return; /* Nothing to draw (excludes 
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1CloseMsg) */ 
GetPort(&thePort2;/* Get current grafPort */ 
/* Get our rectangle (only 1DrewMsg, lHiliteMsg should get 
past */ 
/* the dataLen test) */ 
box = *rect; /* Маке а copy so we can change it */ 
box.top += 2; 
box.left += 16; 
box.bottom - box.top * 32; /* Icons ere 32 pixels */ 
box.right = box.left + 32; 
/* dataLen is already set */ 
LGetCellC&listData, &deteLen,ce11, handle); 
Switch (message) ( 
case 1ОганМ50: 
EraseRect (rect); 
PlotIconC&box,listData. icon); 
/* If name begins with “а.” then ignore pref ix */ 
if CClistData.name[1] == ‘a’ || listData.name[1] == 
A’) && 
listData.name[2] == ‘_’) ( 
/* Make а copy, since listData has filename */ 
displeyNeme[90] = listData.name[@] - 2; 
e me ЕИ ан 
else 
BlockMove(&1istData.name[@],&displayName(O), 
(long)listData.name[0] + 1L); 
TextFont( geneva); 
TextSizeC9); 
MoveToCrect-?left + 32 - StringWidthCdisplayName) / 


rect-? top + 32 + 12); /* Center the name */ 
DrawStringCdisplayName); 
/* Restore typestyle to assumed value */ 
TextFontCsystemFont); 
TextSize(C 12); 
if С!Сѕе1есі & 0х100)) 

break; 
/* else fall through */ 

case lHiliteMsg: 

/* Set up the bit map */ 
iconBits.rowBytes = 4; 
SetRect(&iconBi ts. bounds,0,0,32,32); 


/* According to Steve Brecher, no need to lock, since 
CopyBits won't alter the heap configuration 
unless а picture or region is being recorded. */ 


iconBits.baseAddr = (char *)(*listData. icon) + 128; 
CopyBitsC&iconBits,&thePort-»portBits, 
&iconBits.bounds,&box, 
srcXor ,NIL2; 
break; 


/* Blit the icon */ 


Acta Document Format 

Written by David Dunham 

©25 September 1987 Maitreya Design 

Maitreya Design 

POB 1480 

Goleta, CA 93116 

This note assumes you are familiar with Acta and its 


terminology. Acta documents have the type ‘OTLN’ and creator 


‘ACTA.’ 


An outline on disk consists of a data fork. This is simply the 


data for each topic in sequence (top-to-bottom order). The file is 
terminated with a zero word. 

Each topic is preceded by its level. Topics at the left margin 
are level 1, their daughters 2, etc. The topic’s attributes indicate 
its type and formatting. Data is preceded by its length as a long- 
word. The data itself is either text (not a Pascal string!) or a 
QuickDraw picture, and is not padded. 

The same format is used for the clipboard; Acta uses a scrap 
type of 'ACTA.' (Italso writes a TEXT scrap.) 


OLMO 


word ATTSIZE long word 


length 
struct TOPIC_ATTRIBUTES ( 
word bType; 


pe; /* TEXTtype, PICTtype */ 
word bAttributes; 


/* currently 0, except for 
optionWord bits */ 
word bFont; /* Typestyle */ 
word bStyle; 
word bSize; 
byte bColor; 
byte bExtra; 
byte firstLine; 
byte expanded; 
word hidden; 


/* color index */ 

/* reserved; currently 0 */ 

/* Show first line only? */ 

/* Y/N */ 

/* Is block hidden (by Collapse)? 
count of hide depth */ 


) 

ВТуре is 1 for а text topic, 2 if the topic is а QuickDraw 
picture. Other values are reserved for future use. BAttributes is 
currently unused and should be left 0, except that the bAttributes 
for the first topic is used to determine the options. BFont, bStyle, 
and bSize determine the typestyle of a topic, and have their usual 
QuickDraw interpretation. BColor is an index into a table of 
color values; 0 is black. BExtrais reserved and should be 0. First- 
Line should be set to TRUE (-1) if the topic is shrunken, FALSE 
(0) otherwise. Expanded is TRUE if the daughters are visible, 
FALSE if they are hidden. If a topic is visible, hidden is 0, 
otherwise it is the number of collapsed ancestors. 

If bAttributes of the first topic is O, the default options of 
alphabetic sort A-Z, no ancestress constraint, and outline current 
topic are used. You can choose different options by setting the 
following bits (all other bits should be left reset). These bits are 
ignored if set on topics other than the first. 

0х0100 numeric sort 

0х0001 7-А sort 

0х0002 single ancestress 
0х0004 “smart quotes” 
0х0020 don’t label pictures 


0х0040 don’t outline current topic 
0х0080 don’t put bullets in Clipboard 


In future releases, additional information (such as TextEdit 
"styl' records) may be added. It will follow the zero word. This 
data can be ignored, as the above format will be used for 
backward compatibility. = 


ақыға 
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Pascal Procedures 


MultiFinder Friendly MacDraw Plotter 


For thepast few months, MacTutor has been running a series 
ofeditorials on the importance of developers getting with the new 
way of doing things. In the last six months, Apple has introduced 
a number of product enhancements that directly affect commer- 
cial software development. These include: 

e  MultiFinder Quasi-Multitasking Finder 
AppleShare File Server 
New Menu Manager with nested menus 
New Color PICT format 
New Color Quickdraw Capability 
New Style-enhanced Text Edit & Clipboard type 
Multiple screen capability 
e Universal Hyper-Text type data base 
e Faster number crunching with 68881 chip 
e New ROM interface files, MPW 2.0 


Lots of new Technical notes fixing old bugs 
New compatibility headaches 

As usually happens when new goodies come on the market, 
everyone looks at their old software and says “how come my 
version of MS___ doesn’t support this?" As programmers and 
developers, we have a responsibility to bring our software up to 
speed as quickly as possible with the new way of doing things. 
For example, the time-consuming dialog box to change text font 
and style is no longer good enough when nested menus can do the 
same job so much faster. Black and white windows, menus and 
documents get old after using color for a few weeks. Big screen 
monitors make old style paint programs frustrating when you 
can’t grow the window, or have to turn off color to keep the 
program from crashing. And program development environ- 
ments that once were speedy now send the Mac into the bit- 
bucket because the developer can’t figure out how to handle the 
switching context with a color video card installed. Even lowly 
debuggers have problems trying to cope with all the system 
enhancements. So while Apple has indeed given us lots of new 
toys, they have also given us lots of new headaches trying to 
understand and upgrade our products to work with everything. If 
you thought it was hard to program the Mac two years ago, pity 
the programmer just getting started today. And the fact that Apple 
has just now managed to cleaned up the documentation in Inside 
Macintosh Volume 5, doesn’t help much. 


Put Up or Shut Up 


After hi-lighting commercial products which have made the 
transition to the new rules of the game, we have decided to put our 
money where our editorial mouth is, and attempt to publish a 
program that illustrates how to incorporate many of the new 
system features Apple has introduced in the last six months. 
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ysax^2 + bx + с 


1x123.000, х2=-2.000 
Two Real Roots, x1, x2 


Slope 0 = (0.5,-6.2) 


Fig. 1 Plotter Program generates hairline plots 
placeable directly in Pagemaker. 


Problem Solving 

Since one of the hottest markets for Macintosh now is in 
engineering environments, we will discuss a typical engineering 
approach to computer use. In aerospace and the defense industry, 
the name of the game is problem solving. You use the computer 
to solve a problem. It may be physics, engineering or math, but 
the computer is the tool for investigating the problem and finding 
a solution. Let's suppose our problem is to build a space shuttle 
that flies rather than blows up. And let's suppose a key part of the 
problem is the equation for modeling the burn rate of the solid 
rocket fuel in the boosters. To make things simple, we will 
assume the modeling equation is quadratic in form. We want to 
use the computer to model this quadratic equation and all others 
like itso we сап determine the best model for the rocket's design. 
The problem most engineers have when trying to use the Macin- 
tosh for problem solving, is they spend so much time figuring out 
how the Mac works, they never get around to the problem! So 
here is a shell program for modeling and simulation programs 
that follows the new Macintosh way of doing things. Our “Plot- 
ter" program analyzes the quadratic equation and plots it with the 
following Mac features: 
Dialog box for user-friendly input of parameters 
Equation plotted as a Quickdraw picture 
Plot can be saved to disk as a PICT file 
Program supports printing: 
e hairline line width for graph 
e Choice of window size or paper size 
Plot Window is growable, zoomable, moveable 
Plot can be opened and edited in MacDraw 
Plot can be placed in Pagemaker 
Uses Quickdraw and Postscript comments 
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° Supports WaitNextEvent for MultiFinder use 
° Quickdraw colors for menus, graph, axis 
° Nested menus allow color changes 


Mac Modeling Requires Quickdraw 

One of the big problems in trying to model equations on the 
Macintosh is how to create a Quickdraw Picture. Naturally you 
could just draw it on the screen as a paint-type bit-map, but then 
you couldn't take advantage of the higher resolution of the 
LaserWriter to show the details of the plot. Once a plot is created, 
you want to be able to save and edit it to add notes, or even move 
the graph around the axis. To do this, the parts of the plot have to 
be created as MacDraw type objects. Yet they also have to be 
grouped or else you end up with 200 date points being re- 
positioned on the page by a careless mouse. When the plot is 
finished you have to be able to print or import it into a program 
like Pagemaker to show it to someone. So how to you create a 
program that does all this? 

Check Your Library! 

First, you make sure your supply to Technical Notes is up to 
date. Many of these features are documented and supported by 
the just released Volume Five of Inside Macintosh, and by a rash 
ofnew Technical Notes released since the last Boston Expo. Here 
are some of the notes that deal with the problems of pictures from 
the point of view of modeling equations. 


° 21 Internal Picture format 11/86 
° 27 MacDraw Picture Format 9/86 
4 59 Pictures and Clip Regions 1/86 
e 72 Optimizing for the Laser 3/86 
° 91 Picture Comments 3/87 
° 152 Using Laser Prep routines 7/87 
° 154 Displaying large PICT files 7/87 
° 155 Handles & Pointers 9/87 
° 181 Picture Comments 11/87 
° 183 Position Independent PS 11/87 


In addition, there is the LaserWriter Technical manual, а 
new PICT File Format Notes, and Mac Example Applications, 
ver. 1.0. These three publications, available from APDA, include 
a wealth of information on how to create and print Quickdraw 
pictures and pic comments, both MacDraw and Postscript com- 
ments. 

The problem of making an application MultiFinder friendly 
is partly addressed in the following technical notes as well as the 
recently released MultiFinder Development Package, ver. 1.0, 
from APDA: 

° 158 Asked MultiFinder Questions 9/87 

° 177 Sleep Parameter problem 11/87 

° 180 MultiFinder Miscellanea 11/87 

One of the best “overview” publications of how to imple- 
ment all of the new goodies, especially color, is Dave Wilson’s 
new note collection, Programming the Macintosh II. This is 
available from MacTutor’s mail order store, in this issue. Dave 
has collected the slides from his Mac II seminar at last year’s 
Boston Expo and published his color paint program source code 
to provide a nice one-stop shopping center for all of the features 
in our program this month. Finally, you should plan on getting the 
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Professional Programmer’ s Extender from Invention Software. 
This contains all of the source code for volumes 1 and 2 of their 
extender products. This is also available from the MacTutor mail 
order store, in this issue. It is much faster to cut and paste source 
code from someone else, then re-invent the wheel yourself. 

For those who like books (and have the time to read them), 
your in luck, if you use Borland’s Turbo Pascal for the Mac. A 
rash of new books have been released including Macintosh 
Turbo Pascal by Tom Swan [Wiley & Sons] and Turbo Pascal for 
the Mac by Leon Wortman [Tab Books]. Borland has also 
released a bunch of goodies including Turbo Pascal Tutor, and 
Numerical Methods Toolbox. 1 make it a habit to just visit my 
local computer bookstore regularly and buy anything with Mac 
on it. Call it a business expense! 

How to Use the New Goodies 

Our program this month features the full Macintosh User 
Interface, as documented in the recently released Human Inter- 
face Guidelines: The Apple Desktop Interface, published Ad- 
dison-Wesley, for Apple. It would be a great challenge to take 
this book as a program definition and attempt to write a demo 
program that included full support for every feature in this book, 
showing how the full User Interface is implemented. The main 
program, and a unit called MyPlotStuff, implement the standard 
event loop for a single window application. Much of this was cut 
from the Multi-Window Text Editor MacTutor published last 
year. As I said, its always faster to cut and paste than re-invent. 
To support color, a color array is set up in the InitMac routine to 
define the eight Quickdraw colors. This way the program can run 
on all Macs without a lot of special programming. (Apple really 
needs to put color quickdraw into the SE so that all machines have 
the same version of Quickdraw, even if they can’t show color.) 

MultiFinder Friendly 

To be considered MultiFinder friendly, an application has to 
call WaitNextEvent and support suspend and resume events 
correctly. Our program works under MultiFinder and is espe- 
cially useful with MacDraw, saving and opening our graphs 
between the two programs. But it wasn’t easy figuring out how 
to do it. The first problem we had was that neither Think’s 
Lightspeed Pascal nor Borland’s Turbo Pascal support the final 
MPW 2.0 interfaces. The latest versions, (LS Pascal 1.11 and 
Turbo Pascal 1.1) both use MPW 2.0 beta interfaces and so donot 
include either the SysEnvirons glue, nor the WaitNextEvent 
interface. To get around this, I added the WaitNextEvent defini- 
tion to the ROM85 library for LS Pascal. Since SysEnvirons is ап 
OS trap, I suspect you can’t call it without assembly glue to 
manage the register set-up so it is commented out in the listing. 
I just assumed the Mac was a Plus, SE or II with the latest system. 

Where is WaitNextEvent 

The MultiFinder documentation says you should call Wait- 
NextEvent if it is present. Otherwise, call GetNextEvent and 
SystemTask. So you have to check the unimplemented trap call 
to find out and seta flag so you will know which event trap to use. 
I did this and after a while I noticed the program always said the 
WaitNextEvent trap was unimplemented. What? I have a Mac II 
with the latest system. How can it be unimplemented? Where is 
it? I called several people, both at Borland and Think, but no one 
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knew the answer. Finally, after studying two sample programs 
from the MultiFinder Developer's package previously men- 
tioned, I noticed their programs didn't seem to have any problem. 
It finally dawned on me. WaitNextEvent is inside MultiFinder! 
Thus it only exists when your application is running under 
MultiFinder, when I suppose it gets patched into the system. 
Under the Finder, it's not there so you have to check for it. You 
would think this little gem would have been included in the 
documentation somewhere. Alas, I don't have either the final 
Volume 5 of IM, nor the final MultiFinder Developer's package! 

Our plot is stored as a picture in a data structure called 
PlotDocHandle. We set up the document in our InitMyWindow 
routine in the normal manner. Note that all the rectangles we will 
need are set here, relative to the window's portRect. We also do 
a ClipRect to set the clipping region of the window's grafport so 
we don't have any Quickdraw problems a la tech note 59. 

Color Menus 

Our InitMyMenus routine includes an apple, file and edit 
menu as well as a nested menu for color and a menu for some 
printing options. The data structures are designed to make it easy 
to check the nested menu items and this code depends heavily on 
both Dave Wilson's programming examples, and other code 
segments I've seen. 

The Mighty Update Event 

Our doMouse, Keydowns, and activate routines are pretty 
standard user interface stuff so no need to go over those here. The 
Update routine, is critical. The ideal for all Macintosh programs 
is to never draw anything! The application creates a Quickdraw 
picture or pictures and then invalidates some portion of the 
Screen, causing an update event. Then, in the Update Event 
routine, youcall DrawPicture to display the results of all the other 
application code that has been maintaining and modifying those 
pictures. It has always been a mystery to me how you create the 
perfect Update Event routine. Here is how ours works: 

° Save and set the current grafport 

e Begin Update to restrict the visRgn to the collection 

of invalid rgns that need updating. 
Erase the window's portRect. 
Set the clip rgn to the window's portRect. 
Draw the picture. 
Draw the grow icon. 

° End the update, restoring the VisRgn. 

Exactly why all of these steps are needed, in that order is a 
mystery to me, but it works. The window’s portRect encloses the 
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content region of the window, which includes everything but the 
title bar. In particular, it includes the scroller and grow icon 
regions. So when you erase that, you have to re-draw the grow 
icon. The picture is drawn in what I call the PicRect, or the 
application area of the content region, not including the scroller 
areas. When a grow window event takes place, these rectangles 
have to be carefully updated so that the next update event will 
work properly. 
MultiFinder Support 

Our doMulti routine implements the suspend and resume 
events from MultiFinder. Basically, it is a carbon copy of our 
activate / deactivate event routine. Since it is not really an event, 
we have to do a lot of processing to check for suspend or resume, 
and for a mouse moved event, if we are supporting that feature of 
MultiFinder. Our program is set up for it, but we don't support it, 
since, for multiple monitors, you have to do a lot of region 
arithmetic I don't fully understand. The beta documentation also 
says we have to call SystemEvent and post an activate event if 
a DA is the front window when we are suspended or resumed. I 
have included this code in our doMulti routine, but it may not be 
necessary. I' m looking forward to checking the final documen- 
tation to see about this. 

Grow Window 

Our MyPlotStuff unit implements the remainder of the usual 
user interface. We have an about box dialog that reads the ID 
string like the new Finder does and displays it. We also find out 
how much memory we have left from whatever MultiFinder has 
allocated to us by calling MaxMem. Our doMenuBar routine 
does the usual menu bar processing, including checking the 
nested color menu items when the user selects a new color. The 
menus also are displayed in the color of the selection thanks to the 
color menu resources Steve Sheets taught us about in past issues 
of MacTutor. 
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Our grow routine is the most important one in this unit. Grow 
works with the update eventto change the window properly when 
it is resized. It is another Macintosh mystery I've never fully 
understood. As I understand it, you have a pre-grow period and 
a post-grow period, determined by when you call SizeWindow. 
I use the routine for both a grow window event and a zoom 
window event. In the case of a zoom, you get the new window 
size from the portRect, which is already set for you by the zoom. 
In the case of a grow, you call GrowWindow to return the new 
window size. I re-calculate the important window rectangles 
both before a SizeWindow and after. SizeWindow changes the 
portRect of the window to the new size. So, first you invalidate 
the scroller, grow and pic rectangles with the old portRect, then 
you SizeWindow to change the portRect, and invalidate the 
scroller, grow and pic rectangles for the new window size. This 
seems to correctly get all the window areas properly drawn 
during the update event. I suspect we may be invalidating to 
many areas and that this can be re-fined so that you only 
invalidate certain rectangles depending on whether the window 
is getting smaller or larger. Also, if you have controls, you can 
move and re-size controls separately, so they can be removed 
from the invalidation by calling the validate trap. If anyone has 
amore efficient grow / update routine for the general case, I' d like 
to see it. 

Saving Our Graph 

Once we have played around with various graphs, it would 
be nice to save them. Our myFileStuff unit does the SaveAs and 
Save functions. To save a picture, you call the standard file dialog 
and if the reply is good, you create the file, open the file, set the 
file position to the start of the file and write something into the 
file. Then you close the file and flush the toilet, er, volume. This 
is the order of calls in our doSaveAs routine, the majority of 
whichiserror checking if anything goes wrong, goes wrong, goes 
WIOng... 

To write our graph out to disk, we simply have to write out 
our quickdraw picture. But first we write a 512 byte blank header. 
This will cause MacDraw to open the PICT file and use it's 
default settings. Our plotter program has no open function so we 
save our document as a MacDraw document so it can be viewed 
later and edited. The picture handle is stored in DrawingPic so we 
doa GetHandleSize and write out that number of bytes to the file, 
passing a pointer to the dereferenced picture handle. After saving 
the picture, we set the window title to the file name and store the 
file name, and volume reference number in our document data 
structure and enable the Save menu item for future use. For the 
Save function, we do the same thing as the SaveAs (they could 
be combined at the expense of clarity) except that we get the file 
name and volume reference number from our document datas- 
tructure rather than from a standard file dialog. 

But Where Do We Actually Model It? 

I told you it was tempting to get lost in the Macintosh 
interface and forgetall about the modeling task our Boss assigned 
us to! We are supposed to be modeling a quadratic equation and 
coming up with some numbers for that next moon shot, notsitting 
around reading Inside Macintosh for the 100th time. Our Solve 
Unit implements the routines to analyze our equation and plot it 
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Plot Parameters : 


Fig. 4 Dialog Box gets our parameters 


by actually creating the quickdraw picture we've been spending 
all this time talking about. We also put up a dialog box to get all 
of the equation parameters and plot characteristics we need. We 
can set the step size, and the scale of both the x axis and the y axis. 
And of course, we can input the three parameters that define the 
general quadratic equation. In our doDialog routine, we get these 
parameters from the user, and remember them so they appear the 
next time the plot function is selected. SetIText is used to set the 
dialog items with the values of the global variables that hold the 
equation parameters. A flag is used to by-pass SetIText if this is 
the first time we have been called, in which case the default 
values from the dialog item resources will be used. This allows 
the user to modify the default values in the resource file with 
ResEdit if he wishes. 

The hard part about the dialog box is converting the user's 
response into real numbers. LS Pascal has a routine called 
ReadString that takes the string variables from the GetDItem trap 
and converts them into integer and real numbers for our equation 
parameters. However, this routine crashes mightily if the user 
types a non-numeric entry in the dialog! So the firstimprovement 
would be to protect yourself by checking the dialog input some- 
how. 

The Quadratic Solution 

The example problem is to find the roots of a quadratic 
equation. The problem in itself is not difficult (this time), but the 
solution technique will be similar for other problems. 

First we should consider what the input specifications will 
be. Among the questions we should ask ourselves about the 
problem are: 

1) What values will be provided as input to the program? 

2) Whatrange will these values be in? 

3) What format will the values be in? 

4) In what ways can these input values be used? Can the 

inputs be modified? 

5) How willthe input values be provided to the program? 

6) What values will be returned by the program? 

7) What format will the return values be in? 

8) What kind of output will be produced? 


Any quadratic equation may be reduced to the form, — 


ax? + bx + c = 0 
then 
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If a, b, and c аге real then: 

If b?-4ac is positive, the roots are real and unequal; 

If b?-4ac is zero, the roots are real and equal; 

If b?-4ac is negative, the roots are imaginary and unequal. 


The inputs required in this problem are a, b, and c. These 
values will be in the set of real numbers. Our dialog box allows 
us to input these values. On our plot, we print the results in a box 
indicating if the analysis yields real, or complex results. We can 
also solve the first derivative problem and determine where the 
graph has a local minimum or a maximum. Our program doesn't 
do it, but we could also indicate the second derivative to show if 
the curve is concave upward or downward. Keep in mind that in 
a “real life" problem the algorithm is not always given as in this 
example. The user normally doesn't care how the program 
arrives at the result as long as the result is correct. If too many 
details are specified early in the defining the problem, the 
programmer may get “locked in" to a particular solution too 
early. The programmer then lacks the flexibility needed to 
choose the best technique to solve the problem. 

Our SolveIt and Quad routines implement the analysis 
portion of our modeling program by solving the quadratic equa- 
tion and checking for the type of result. When the user selects Plot 
from the file menu, our doPlot routine will call Solvelt, which in 
turn calls Quad to get the “answers”. With answers in hand, we 
call PlotMe to create a quickdraw picture and display it in our 
window. After creating the picture with OpenPicture and Close- 
Picture, we get the picture displayed by simply invalidating the 
window's portRect. This forces an update event, when will draw 
the graph by calling DrawPicture in our update event routine. 
Thus the whole plotter program really boils down to the magical 
routine which creates this quickdraw picture. This routine is 
called PrQDPicStuff in our Solve unit and is the most important 
of the whole program. 

Creating the Quickdraw Picture 

When we call OpenPicture, the characteristics of the current 
grafport will be used to determine how the picture will be stored. 
In our PrQDPicStuff routine, we want to allow for drawing either 
the picture on the screen or on the printer. We do this by passing 
to the routine, the display rectangle for the picture and a parame- 
ter indicating if we have been called from the Plot function or 
from the Print function. This was done to allow the added printer 
option of printing the graph using the full printer page, rather than 
thé window's portRect. While printing to full page size is not 
WYSIWYG, itis useful to get the biggest plot possible when you 
are trying to analyze a function’s behavior. In addition, if we are 
printing on the laserwriter, we set the font to times instead of 
geneva. 

Constructing the picture definition routine is important. In 
our program we have grouped all the tasks together. First we 
calculate all the program variables, from the picture rectangle's 
width and height. We get the font information from GetFontInfo 
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so our paragraph can be constructed properly. The initial x and 
y values are calculated. These real values are converted into 
integer coordinates for plotting in such a way that the plot axis 
will extend the full length and height of the picture rectangle. 

Next all the text is constructed with LS Pascal's StringOf 
command and stored in Macintosh strings. For our paragraph, we 
use an array of strings which will be used to display the analysis 
results: the roots of the equation, the local min/max point, and the 
equation's defining parameters. Once all the initial calculations 
and strings are set up, we are ready to ‘draw’ into our picture. 

We set the background, axis and graph colors as set by the 
color menu items checked. We draw a box around the graph 
boundary (the display rectangle). We draw the axis, the plot 
itself, anda box for our paragraph. Finally we draw the paragraph 
and dispose of our temporary handles and clip regions. 

Pic Comments 

In order to get MacDraw to display our graph, the objects we 
draw must be grouped together. In particular, the graph itself 
must be grouped so all those little line segments stick together. A 
Pic Comment is used to do this. Pic Comments allow commands 
to be imbedded within the picture definition. There are two 
published lists of Pic Comments in the technical notes. One is the 
Pic Comments that MacDraw recognizes. The other are the Pic 
Comments that Postscript recognizes. Using these two sets of Pic 
Comments will enhance an application's ability to create pictures 
that can be imported into other applications or that can take 
advantage of new capabilities. Apple is supposed to be keeping 
alist of registered Pic Comments, but little has come from it. The 
power of QuickDraw's Pic Comments has really not been ex- 
ploited or pushed by Apple in comparison to postscript. 

PostScript Pic Comments 

Since Quickdraw cannot do hairlines, we need to use some 
postscript Pic Comments the LaserWriter understands to set the 
line width thinner than that possible by Quickdraw. To get a 
hairline, define: 


pe 
widhdl = ^widptr; 
widptrz^widpt; 
widpt-Point; 
Var 
Width:Widhdl; 


Then set up Width as follows: 
Width**.h:=10; 
Width**.v:=1; 


Then use a Pic Comment: 
PicComment(SetLineWidth,2,Handle(Width)); 


We can also draw our text so that it will be grouped as a 
paragraph by using the TextBegin and TextEnd comments. With 
the PicGrpEnd and PicGrpBegin comments we can group objects 
so that they stay together when moved around in MacDraw. 

Printing Our Graph 

Once our picture is defined, we can print it when the user 
selects print from the file menu. To print, we call our PrQDStuff 
routine above with the printing rectangle obtained from the Print 
Setup dialog and the display device set to LaserWriter. 


© The Definitive MacTutor, Vol. 4 


PrODStuff will re-create the picture to the page rectangle, if the 
print option is selected, and a simple DrawPicture command 
during an open printing grafport will send the picture to the 
printer. The print traps are now in the system file, so we no lon ger 
link to the printing glue. In our doPrint routine, we get our print 
handle, saved in our document definition, save the current 
grafport and call PrOpen. Then we validate our print record and 
call PrJobDialog to put up the printing dialog box. If the user 
selects print, then we open the printing grafport by calling 
PrOpenDoc followed by PrOpenPage. From the printing info 
record (prInfo.rPage) we get the PageRect to pass to our picture 
creation routine. The PrintMe routine opens the picture and re- 
creates it using the PageRect, justas our PlotMe routine set up the 
picture for drawing to the screen. After drawing the picture into 
the printing grafPort, we close the page, close the document and 
close the printing manager by calling PrClosePage, PrCloseDoc 
and PrClose respectfully. When the printing grafPort is opened, 
the low level Quickdraw primitives are replaced with pointers 
into the printing manager, where the printer equivalent of the 
Quickdraw primitives translate the quickdraw picture definition 
into LaserPrep commands, which in turn are defined by the 
LaserPrep file into Postscript, and then interpreted by the Post- 
script interpreter in the LaserWriter into an image on the page. 
How does Postscript image the page? I don’t know. If I did know, 
I'd build a Postscript photo-typesetter, buy an Adobe Atlas board 
and have myself a 2700 dot per inch typesetting machine with- 
out paying Allied Linotype $50,000. 
New Goodies Not Addressed 

The key to this program is the fact that it produces a 
document that can be read, edited and placed by two other 
popular programs. In this way, the Plotter Program illustrates an 
important rule in the MultiFinder world: applications should 
work together to produce a library of 
compatible tools. The best way this can 
happen is by formatting the output of 
similar tools to read and write compat- 
ible documents. The MacDraw PICT 
file, the MacPaint bit-map file and the 
Mac Write formatted text file are impor- 
tant document standards that many 
similar tools support, besides the nearly 
universal unformatted text file. Even 
though Apple has defined a standard 
style definition for Text Edit that allows 
for font changes, we have yet to see a 
widely used formatted text item type 
that is a standard across many applica- 
tions. 

Apple Share is another new goodie 
that affects developers. How do we 
make Apple Share compatible pro- 
grams? Consider this: To be MultiFin- 
der friendly, Apple says you should 
keep track of where your windows were 
moved last. That means you have to 
write something to disk to save this in- 
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formation, but where? If you write it in the resource fork, the most 
logical place, then your program can’t be Apple Share compat- 
ible since the resource fork is not sharable. Two users cannot 
write to the same resource fork without destroying the integrity 
of the file. So Apple has created a catch-22 situation; supporting 
one new goodie (MultiFinder) makes it impossible to support 
another (Apple Share). Apple’s recommended solution is to 
write a “configuration file” into the system folder. Great. Now 
our hard disks will have hundreds of little configuration files to 
keep track of! Since the resource manager is Apple Share brain 
damaged, it hardly seems realistic for Apple to expect 
developer’s to rush madly to embrace this goodie. We encourage 
Apple to continue to define and support compatible data formats 


50 tools can be used together. 


( Quadratic Equation Example program } 
( By Dave Kelly & Dave Smith 
( @MacTutor, 1988 ) 


PROGRAM QuadraticPlotter; 


USES 
ROM85, PrintTreps, PlotGlobals, Misc, myP lotStuff; 


PROCEDURE crash; 
BEGIN 
ExitToShe11; 
END; 


PROCEDURE InitMac; 
VAR 
err : 05Егг; 
BEGIN 
МахАрр17опе; 
MoreMasters; 
MoreMasters; 


y-ax 2 + Dx + c 

a=1.0, b=5.0, с=2.0 
Х1=-0.438, x2=-4.562 
Two Real Roots, x1, x2 
Slope 0 = (-2.5,-4.2) 


x “m mW WU ees ман жан тты "E (a ea x m-s 2-3 4 + 
E 


Fig. 6 Pic Comments group objects for editing in MacDraw. Note that 
MacDraw ignores hairline Pic Comment! 
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MoreMasters; 
MoreMasters; 
MoreMasters; 
InitGraf CéthePor t); 
InitFonts; 
InitWindows; 
InitMenus; 

TEInit; 
InitDialogs(@crash) ; 
InitCursor ; 
FlushEventsCeveryEvent, 2); 
Finished := false; 
dialogflg := false; 


GoAway := true; 
RefVal := 0; 
title := ‘Quadratic Plotter’; 


PlotWindow := NewWindow(NIL, PlotWindowRect, title, 
Visible, windtype, pointer(-1), GoAway, RefVal); 

PlotWindowPeek := WindowPeekCPlotWindow); 

SetPortCPlotWindow); 

TextFont(Geneva); 

TextSizeC 10); 

ТехіҒасеС 11); (plain) 

ТехіМодес 1); (Or) 

Репћогта1; 

ForeColor(blackColor ); 


BackColor(whiteColor2; 


color[1] := 33; (black) PlotDocHandle := DocHandle(NewHandle(sizeof CDocument?)2); 
color{2] := 38; (white) PlotWindowPeek* .refCon := LongInt(PlotDocHandle); 
color[3] := 205; (гед) PlotWindowPeek^ .windowKind := userKind; 
со10г141 := 341; (green) PlotDocHandle**.drawing := NIL; 
color(5] := 409; (blue) WITH PlotWindow^.portRect DO 
color(6] := 273; (суап) BEGIN 
color[7] := 137; (magenta) SetRect(VCRect, right - (SBarWidth - 1), top - 1, 
colorí8] := 69; (yellow) right + 1, bottom - (SBerWidth - 2225; 
SetRect(HCRect, left - 1, bottom - (SBarWidth - 1), 
theWorld.machineType := 4; (Мас II) right - (SBerWidth - 2), bottom * 1); 
(err := SysEnvirons(1, theWorld); not in LSP 1.11) SetRect(GrowRect, HCRect.right, HCRect. top, 
typeOfMac := theWorld.machineType; VCRect.right, HCRect bottom); 
SetRect(PicRect, left, top, right - (SBarWidth - 
IF CtypeOfMac >= Ø) AND (NGetTrapAddressCWNETrapNum, 1), bottom - (SBarWidth - 122; 
ToolTrap) = NGetTrapAddress(UnImp1TrapNum, ToolTrap)) THEN SetRect(PageRect, left, top, right - (SBarWidth - 
BEGIN 1), bottom - (SBarWidth - 1)); 
WNE := FALSE; END; (of with } 
doMessage( ‘WaitNextEvent not implemented’, °’, ‘’, ClipRect(PlotWindow*.portRect); 
е); (Only true under Multif inder) myPrint := THPrintCNewHandle(SIZEOFCTPrint))); 
END PlotDocHandle^^.Print := myPrint; 
ELSE END; 
WNE :- TRUE; 
mouseRgn := NewRgn; PROCEDURE InitMyMenus; 
END; VAR 
i : integer; 
PROCEDURE initRects; BEGIN 
VAR myMenus [AppleM] := GetMenuCAppleMenu?; 
MemoryPtr : ^Integer; AddResMenu(myMenus [AppleM], 'DRVR'); 
BEGIN myMenus[FileM] := GetMenu(CF ileMenu); 
MemoryPtr := pointer(mBarHeightGlobal); myMenus(EditM] := GetMenuCEdi tMenu); 
mBarHeight := МетогуР4г^; myMenus [ColorM] := GetMenu(ColorMenu); 
Screen := ScreenBits.Bounds; (current screen device) myMenus [Option] := GetMenuCOptionMenu) ; 
SetRect(DragArea, Screen. left + 4, Screen.top + mBar- myMenus(GraphM] := GetMenuCGraphMenu); 
Height + 4, Screen.right - 4, Screen.bottom - 4); myMenus[AxisM] := GetMenuCAxisMenu); 
SetRect(GrowArea, Screen. left + MinWidth, Screen.top + myMenus [BackgroundM] := GetMenu(BackgroundMenu); 
MinHeight, Screen.right - 8, Screen.bottom - 8); 
SetRect(PlotWindowRect, Screen.left + 15, Screen.top + FOR i := 1 TQ MenuCount DO 
45, Screen.right - 75, Screen.bottom - 50); InsertMenu(myMenus(il, 0); 
SetRect(ZoomRect, Screen. left + 4, Screen.top + mBar- FOR i := SubMenuStert TO TotalMenuCount DO 
Height * 4, Screen.right - 4, Screen.bottom - 4); InsertMenuCmyMenuslil, -1); 
END; 
GraphColor := 3; 
PROCEDURE InitMyWindow; CheckItemCmyMenus[GraphM], GraphColor, true); 
VAR AxisColor := 1; 
windtype : integer; CheckI tem(myMenus[AxisM], AxisColor, true); 
Visible : boolean; BackgroundColor := 2; 
GoAway : boolean; CheckI tem(myMenus[BackgroundM], BackgroundColor, true); 
RefVal : LongInt; 
title : str255, CheckItem(myMenus[OptionM], 1, true); 
myPrint : THPrint; Option := 1; (window rect printing) 
BEGIN 
Visible := false; DrawMenuBar ; 
windtype := documentProc + ZoomBox; END; (of proc) 
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PROCEDURE doMouse (myEvent : EventRecord); 
VAR 
whereIsIt : integer; 
whichWindow : WindowPtr; 
localPt, globalPt : Point; 
oldPort : GrafPtr; 
BEGIN 
globalPt := myEvent.where; 
localPt := globalPt; (global coord of mouse} 
GlobalToLocalClocalPt); {local coord of mouse) 
whereIsIt := FindWindowCglobalPt, whichWindow); 
CASE whereIsIt OF 
inDesk : (0) 
doMessage('Mouse Click on Desktop.’, “(Not 


handled in this program.)’, “2”, 40; 


inMenuBar : (1) 
doMenuBar (MenuSelect(globalPt)); 
inSysWindow : (2) 
SystemClick(myEvent, whichWindow); 
inContent : (3) 
doContent(myEvent, whichWindow); 
inDrag : (4) 
doDrag(whichWindow, globalPt); 
inGrow : (5) 
doGrow(whichWindow, globalPt, False); 
inGoAway : (6) 
IF TrackGoAwayCwhichWindow, globalPt) THEN 
HideWindow(whichWindow); 
inZoomIn, InZoomOut : (7, 8) 
BEGIN 
IF TrackBox(whichWindow, globalPt, whereIsIt) THEN 
BEGIN 
GetPortCOldPort); 
SetPortCwhichWindow); (safety device) 
EraseRect(whichWindow* .portRect); 
ZoomWindowCwhichWindow, whereIsIt, True); 
doGrowCwhichWindow, globalPt, True); 
SetPortCO1ldPort); 
END; 
END; 
OTHERWISE 
BEGIN 
END; 
END; (of whereIsIt) 
END; 


PROCEDURE doKeyDowns (myEvent : EventRecord); 
VAR 


ch : cher; 
charCode : longInt; 
keyCode : longInt; 


BEGIN 
charCode := BitAnd(myEvent Message, charCodeMask); 


keyCode := BitShif t(BitAnd(myEvent Message, keyCodeMask), -8); 


ch := ChrCcharCode); (get keyboard char) 
IF BitAndCmyEvent Modifiers, CmdKey) = CmdKey THEN 
doMenuBar(MenuKey(ch)) ( do menu command key) 
ELSE 
BEGIN ( do keystroke ) 
PeremText('No typing supported.^, '^, ”, 4); 
itemhit := CautionAlertCAlertDialog, NIL); 
END; (of do key stroke ) 
END; (of proc) 


PROCEDURE doUpdates (myEvent : EventRecord); 
VAR 


О The Definitive MacTutor, Vol. 4 


UpdateWindow : WindowPtr; 
TempPort : GrafPtr; 
BEGIN 
UpdateWindow := WindowPtr(myEvent .message?; 
IF UpdateWindow - PlotWindow THEN 
BEGIN 
GetPort(TempPort); (save port) 
SetPor t(UpdateW indow); 
Beg inUpDate(CUpdateW indow); 
BackColorCwhiteColor); 
EraseRect CUpdateWindow~ .рог{Кес{); 
ClipRectCUpdateW indow^ .portRect); 
DrawPicture(DrawingPic, PicRect); 
DrawGrowIconCUpdeteWindow); 
EndUpDateCUpdateWindow); 
SetPort(TempPort); (restore port) 
END; 
END; (of proc) 


PROCEDURE doActivates (myEvent : EventRecord); 
VAR 
TergetWindow : WindowPtr; 
TergetPeek : WindowPeek; 
BEGIN 
TergetWindow := WindowPtr(myEvent .message); 
TergetPeek := windowPeek(TargetWindow); 
SetPort(TargetWindow); 
IF Odd(myEvent modifiers) THEN 
BEGIN (activate) 
IF TargetWindow = PlotWindow THEN 
BEGIN 
DisableItem(myMenustEditM], eUndo); 
DisebleItemC(myMenus[EditM], eCut); 
DisebleItem(myMenus[EditM], eCopy); 
Disableltem(myMenus[EditM], ePaste); 
DisableItem(myMenus[EditM], eClear); 
DrawGrowIcon(Targe tW indow); 
END 
END ( of activate loop} 
ELSE 
BEGIN (deactivate) 
IF TargetWindow = PlotWindow THEN 
BEGIN 
EnableItem(myMenus [EditM], eUndo); 
EnableItem(myMenus[EditM], eCut); 
EnebleItem(mgMenus [EditM], eCopy); 
EnableItem(myMenus [EditM], ePaste); 
EnebleItem(myMenus [EditM], eClear); 
DrawGrowIcon(TergetWindow); 
END; ( of my window activation) 
END; (of deactivate loop) 
END; (of proc) 


PROCEDURE doMulti (myEvent : EventRecord); 


CONST 
MouseMovedEvt > $FA; 

VAR 
HiByte : byte; 
bit? : LongInt; 
sysresult : boolean; 
ResumeWindow : WindowPtr; 
ResumePeek : WindowPeek; 
SuspendWindow : WindowPtr; 
SuspendPeek : WindowPeek; 
MouseMove : LongAndByte; 

BEGIN 
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6140 := 31; (convert 68000 to toolbox) 
MouseMove. longView := myEvent.message; 
HiByte := Byte(MouseMove .byteView.byte0); 
IF HiByte - MouseMovedEvt THEN 
BEGIN (Handle mouse moved event) 
END; 
(check for resume event ) 
IF Odd(myEvent.message) THEN 
BEGIN (resume) 
(activate Event) 
ResumeWindow := FrontWindow; 
IF ResumeWindow - PlotWindow THEN 
BEGIN 
SetPor tCResumeWindow?; 
InvalRectCResumeWindow^ por tRect); 
DisebleItemC(myMenus(EditM], eUndo); 
DisebleItemC(myMenus[EditM), eCut); 
DisebleItem(myMenus [EditM], eCopy); 
DisableItem(myMenus[EditM], ePaste); 
DisebleItemCmyMenus(EditM], eClear); 
DrawGrowIcon(ResumeW indow ); 
END; 
IF FrontWindow € NIL THEN 
BEGIN (DA check) 
ResumePeek :- WindowPeek(FrontWindow); 
IF ResumePeek^ .windowKind < Ø THEN (DA) 
BEGIN 
myEvent.what := activateEvt; 
BitSetC@myEvent .modifiers, 61102; 
sysresult := SystemEvent(myEvent); 
END; (de) 
END; (DA check) 
( end of activate Event) 
END (of resume) 


LSE 
BEGIN (suspend) 
(de-activate Event) 
SuspendWindow := FrontWindow; 
IF SuspendWindow = PlotWindow THEN 
BEGIN (plotwindow) 
SetPor t (SuspendW indow?; 
InvalRectCSuspendW indow^ . por tRect ); 
EnebleItem(nyMenus [Edi tM], eUndo); 
EnebleItem(nyMenus (Edi tM], есу; 
EnableI temCmyMenus[EditM], eCopy?; 
EnableI temCmyMenus[EditM], ePaste); 
EnebleItem(myMenus [EditM], eClear); 
DrewGrowIcon(SuspendWindow); 
END; (plotwindow) 
IF FrontWindow € NIL THEN 
BEGIN (DA check) 
SuspendPeek := WindowPeekCFrontWindow); 
IF SuspendPeek^ .windowKind < 0 THEN 
BEGIN (de) 
myEvent.what := activateEvt; 
BitCIrCemyEvent modifiers, 5110); 
sysresult := SystemEvent(myEvent); 
END; (de) 
END; (ОА check) 
( end of de-activate Event) 
END; (suspend) 
END; (of proc) 


PROCEDURE MainEventLoop; 
CONST 
MultiFinderEvt = 15; 


VAR 
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sleep : LongInt; 
Event : EventRecord; 
DoIt : Booleen; 
BEGIN 
Sleep := 10; 
ВЕРЕАТ 
IF WNE THEN 
DoIt := WaitNextEventCEveryEvent, Event, sleep, NIL) 


SustemTask; 
DoIt := GetNextEvent(EveruEvent, Event); 
END; 
IF DoIt THEN 
CASE Event .what OF 
mouseDown : 
doMouse(Event); 
KeyDown, Autokey : 
doKeyDowns(Event); 
updateEvt : 
doUpdates(Event); 
activateEvt : 
doActivates(Event); 
MultiFinderEvt : 
doMultiCEvent); 
OTHERWISE 
BEGIN 
END; 
END; (of event cese) 
UNTIL Finished; (end program) 
END; 


( Main Program) 
BEGIN 
Іпі Мас; 
InitRects; 
Ini tMyWindow; 
InitMyMenus; 
MainEventLoop; 
END. 


UNIT MyPlotStuff ; 
INTERFACE 


USES 
ROM85, PrintTreps, PlotGlobals, Misc, solve, MyFileS- 
tuff, MyPrintStuff; 


PROCEDURE doAbout; 

PROCEDURE doQuit; 

PROCEDURE doMenubar (menuResult : LongInt); 

PROCEDURE doContent (ConEvent : EventRecord; 
contentWindow : windowPtr ); 

PROCEDURE doDrag (GrabWindow : WindowPtr; 
GlobalMouse : point); 

PROCEDURE doGrow CResizeWindow : WindowPtr; 
Globalmouse : point; 
Zoomflg : Boolean); 

IMPLEMENTATION 


PROCEDURE do^About ; 
VAR 
IDStrHandle : StringHandle; 
dialogP : DialogPtr; 
item : integer; 
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Stri, $472, Str3 : str255; 
myHeapSpace : LongInt; 
FreeSpace : Size; 


BEGIN 


END; 


IDStrHendle := StringHandleCGetResource(rsrc, 82); 
IF IDStrHandle - NIL THEN 

BEGIN 

doMessage(’Get About box crash!’, °’, ””, 
ExitToShe11; 

END; 
MoveHHi CHandleCIDStrHandle)); 
HLockCHandleCIDStrHandle?); 
FreeSpace :- FreeMem; 
myHeapSpace := MaxMem(FreeSpace); 
NumToStr ing(myHeapSpace, Str2); 
Str2 := concatC'Memory = ”, Str2); 
Str3 := “/, 
Str] s t"; 
PeremTextCIDStrHandle^^, Str1, Str2, $173); 
dialogP := GetNewDialog(AboutDialog, NIL, pointer(-1)); 
IF dialogP = NIL THEN 
BEGIN 
doMessage( ‘Dialog crash!’, ‘We are dead...’, '', 4%); 
ExitToShe11; 
END; 
initCursor; 
ModalDialog(NIL, item); 
DisposDialog(dialogP); 
HUnlockCHandleCIDStrHandle)); 


егу» 
4 
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PROCEDURE doQuit; 
BEGIN 


BackColor(whiteColor); 
ForeColor(blackColor ); 

PenNormal; 
DisposeWindowCPlotWindow); 
DisposeRgn(mouseRgn); 
DisposHendleCHandleCPlotDocHandle)); 
Finished := true; 


END; (of proc) 


PROCEDURE doMenubar; ((menuResult : LongInt)) 


BEGIN 


VAR 
theMenu : integer; 
theItem : integer; 
daName : STR255; 
accItem : integer; 


temp : GrafPtr; 


theMenu := HiWord(menuResult); (menu) 
theItem := LoWord(menuResult); (item) 
CASE theMenu OF 


AppleMenu : 
BEGIN 
IF theItem = eAbout THEN 
doAbout 
ELSE 


BEGIN (must be DA) 
GetItem(myMenus[AppleM], theItem, daName); 


GetPort(temp); (protect against flacky DA) 
accltem := OpenDeskAcc(daName); 
SetPort( temp); 


END; (else) 
END; (of AppleMenu) 


FileMenu : 


BEGIN 
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EditMenu : 


BEGIN 


CASE theItem OF 
fPlot : 
BEGIN 
doPlot; 
END; 
fSave : 
BEGIN 
doSave; 
END; 
fSaveAs : 
BEGIN 
doSaveAs; 
END; 
fPageSet : 
BEGIN 
doPageSet ; 
END; 
fPrint : 
BEGIN 
doPr int; 
END; 
fQuit : 
BEGIN 
doQuit; 
END; 
OTHERWISE 
BEGIN 
END; 
END; (of theitem) 
END; (of FileMenu) 


IF NOT SystemEditCtheitem - 1) THEN 


BEGIN 
CASE theItem OF 
eUndo : 
BEGIN 
END; 
eCut : 


END; 
OTHERWISE 
BEGIN 
END; 
END; (of case) 
END; (of system edit) 
END; (of EditMenu) 


ColorMenu : 


BEGIN (just а dummy for submenus) 
END; (of color menu) 


GraphMenu : 


BEGIN 

CheckItemCmyMenus[GrephM], GrephColor, false); 
GrephColor := theitem; 

CheckI temCmyMenus[GraphM], GraphColor, true); 
END; (of graph menu) 


AxisMenu : 


BEGIN 
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CheckI temCmyMenus[AxisM], AxisColor, false); 


AxisColor := theitem; 
CheckI temCmyMenus[AxisM], AxisColor, true); 
END; (of exis menu) 
BackgroundMenu : 
BEGIN 


CheckItemCmyMenus [BackgroundM], BackgroundColor, false); 


BackgroundColor := theitem; 
CheckItem(myMenus (BackgroundM], BackgroundColor, true); 
END; (of background menu) 
OptionMenu : 
BEGIN 
CheckI temCmyMenus[OptionM], Option, false); 
Option := theitem; 
CheckItem(muMenus[OptionM], Option, true); 
END; 
OTHERWISE 
BEGIN 
END; 
END; (of theMenu) 
HiliteMenu(0); (un-hilite selected menu) 


END; 
PROCEDURE doContent; ((ConEvent : EventRecord) 
(contentWindow : windowPtr);} 
VAR 
localPt, globalPt : Point; 
part : integer; 
myRect : Rect; 
control : ControlHandle; 
BEGIN 


IF contentWindow © FrontWindow THEN 
SelectWindowCcontentWindow2; 

globalPt := ConEvent .where; 

localPt := globalPt; (global coord of mouse) 

GlobalToLocal(localPt); (local coord of mouse) 

part := FindControlClocalPt, contentWindow, control); 


IF contentWindow = PlotWindow THEN 
BEGIN 
SetPor tCPlotWindow); 
IF part © 0 THEN 
BEGIN (in control) 
END; 
IF part - 0 THEN 
BEGIN (content region) 
myRect := PlotWindow^ .portRect ; 
IF PtInRectClocalPt, myRect) THEN 
BEGIN 
END; (of ptInRect) 
END; ( of part=0 ) 
END; (of contentwindow) 
END; (of proc) 


PROCEDURE doDrag; ((GrabWindow : WindowPtr) 
(GlobalMouse : point2;) 
BEGIN 
DregW indowCGrabWindow, GlobalMouse, ОгадАгеа); 
END; 


PROCEDURE doGrow; ((ResizeWindow : WindowPtr; } 
(Globalmouse : point;) 
(ZoomF 1g:Boolean?;) 
VAR 
newSize : LongInt; 
hsize : integer; 
vsize : integer; 
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oldPort : GrafPtr; 
myRect : rect; 
tempLong : LongInt; 
BEGIN 
IF (ResizeWindow <> FrontWindow) THEN 
SelectWindowC(ResizeWindow) 


ELSE 
BEGIN 
IF (ZoomF1lg) THEN 
BEGIN 
WITH ResizeWindow^.portRect DO 
BEGIN 


tempLong := bottom - top; 
newSize := BitShiftCtempLong, 16); 
newSize := newSize + (right - left); 
END; 
END 
ELSE 
newSize := GrowWindow(ResizeWindow, Globalmouse, GrowArea); 
IF newSize ‹› 0 THEN 
BEGIN (grow the window) 
hsize := LoWord(newSize); 
vsize := HiWord(newSize); 
IF ResizeWindow = PlotWindow THEN 
BEGIN 
WITH ResizeWindow^.portRect DO (Pre-Grow) 
GIN 
SetRect(VCRect, right - (SBarWidth - 1), top - 1, right + 1, 
bottom - (SBarWidth - 225; 
SetRectCHCRect, left - 1, bottom - (SBarWidth - 1), right - 
(SBarWidth - 25, bottom + 1); 
SetRect(GrowRect, HCRect.right, HCRect.top, VCRect.right, 
HCRect .bottom); 
SetRect(PicRect, left, top, right - (SBarWidth - 1), bottom - 
(SBarWidth - 15); 
END; (of with ) 
InvalRectCVCRect 2; 
InvelRectCHCRect ); 
InvalRect(GrowRect); 
SizeWindow(ResizeWindow, hsize, vsize, TRUE); (new portRect) 
WITH ResizeWindow^.portRect DO (Post Grow) 
BEGIN 
SetRectCVCRect, right - (SBarWidth - 1), top - 1, right + 1, 
bottom - (SBarWidth - 222; 
SetRectCHCRect, left - 1, bottom - (SBarWidth - 1), right - 
(SBarWidth - 25, bottom + 1); 
SetRect(GrowRect, HCRect.right, HCRect.top, VCRect.right, 
HCRect.bottom); 
SetRect(PicRect, left, top, right - (SBarWidth - 1), bottom - 
(SBarWidth - 122; 
SetRect(PageRect, left, top, right - (SBarWidth - 1), bottom - 
(SBarWidth - 12); 
END; (of with ) 
InvalRectCVCRect?; 
InvalRectCHCRect 2; 
InvalRect(GrowRect); 
InvalRect(PicRect); 
END; (of if ResizeWindow) 
END; (of grow window stuff) 
END; (of if then newsize) 
END; (of proc ) 


END. (of unit) 


UNIT MyFileStuff; 
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INTERFACE 


USES 
ROM85, PrintTreps, PlotGlobals, Misc; 


PROCEDURE doSaveAs; 
PROCEDURE doSave; 


IMPLEMENTATION 


PROCEDURE доЗауеАз; 
LABEL 
1, 2; 
CONST 
SFPutLeft = 82; 
SFPutTop = 50; 
headerBytes = 512; 
TYPE 
DrawHeader = RECORD 
fill : ARRAY[1..2561 OF integer; 
END; 
VAR 
SFPutPt : Point; 
theReply : SFReply; 
err : OSErr; 
refNum : Integer; 
bytes : LongInt; 
myWindow : WindowPtr; 
title : str255; 
myType : OSType; 
myCreator : 05Туре; 
stri, str2 : str255; 
header : DrawHeader ; 
i : integer; 
myPicture : PicHandle; 
PicLength : LongInt; 
BEGIN 
myPicture := PlotDocHandle^^ Drawing; 
IF nyPicture - NIL THEN 
doMessageC'No picture to save yet!^, '^, '’, °’) 
ELSE 
BEGIN 
SetPtCSFPutPt, SFPutLeft, SFPutTop); 
WITH header DO 
BEGIN 
FOR i := 1 TO headerBytes DIV 2 00 
filllil := 0; 
END; 
bytes := headerBytes; 
myWindow := PlotWindow; 
GetWTitleCmyWindow, title); 
SFPutFileCSFPutPt, ‘Save Plot as..’, title, NIL, theReply); 
IF theReply.good THEN 
BEGIN (theReply.good) 
nyType := ‘PICT’; 
myCreator := ‘MDRW’; (MacDraw doc) 


err := Create(theReply.fname, theReply.vRefNum, myCreator, 
myType ); 
IF err © noErr THEN 
BEGIN (err<>noErr) | 
IF err = dupFNErr THEN 
BEGIN (err=dupFNerr) 
err :- FSDeleteCtheReply.fname, theReply.vRefNum); 


IF err € noErr THEN 
BEGIN (erronoErr) 

doMessage('Cannot delete duplicate file.’, '', '’’, '’); 
6070 1; 
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END; (err О поЕгг) 
err := CreateCtheReply. fname, theReply.vRefNum, myCreator, 
nyType?; 
IF err © noErr THEN 
BEGIN (егг о поЕгг) 
doMessageC'Cannot create file...’, ”, '’’, 49; 
GOTO 1; 
END; (erronoErr) 
END (err=dupFNerr) 
ELSE (create f ile error) 
BEGIN (create file error) 
doMessage( ‘Cannot create new file...’, '^, '^, 4); 
GOTO 1; 
END; (create file error) 
END; (erro noErr) 
err := FSOpen(theReply.fname, theReply.vRefNum, refNum); 
IF err О noErr THEN 
BEGIN 
doMessage('Cennot open file...’, 90097-74); 
GOTO 1; 
END; 
err := SetFPos(refNum, FSFromStart, 0); 
IF err © noErr THEN 
BEGIN 
doMessageC'Cannot set start of file...’, '^, '’, '’); 
GOTO 2; 
END; 


err := FSWriteCrefNum, bytes, 6header); 
IF err © noErr THEN 
BEGIN 
doMessage( ‘Cannot write header to file...’, '^, ”, 4); 
GOTO 2; 
END; 
IF bytes © 512 THEN 
BEGIN 
NunToString(bytes, str1); 
stri := concat(str1, ' bytes’); 
Str2 := concet('out of ', (5127; 
doMessage(‘Only able to write ', stri, str2, ‘to file.’); 
GOTO 2; 
END; 
PicLength := GetHandleSizeCHandle(DrawingPic)); 
bytes := PicLength; 
err := FSWrite(refNum, bytes, pointer(DrawingPic*)); 
IF err € noErr THEN 
BEGIN 
doMessage( ‘Cannot write picture to file...’, 7, 9, (^y; 
GOTO 2; 
END; 
IF bytes € PicLength THEN 
BEGIN 
NumToString(bytes, str1); 
str1 := concet(stri, ' bytes’); 
NumToString(PicLength, str2); 
str2 := concat(‘out of ”, str2); 
doMessage(‘Only able to write ”, stri, str2, ‘to file.’); 
GOTO 2; 
END; 
SetwWTitleCmyWindow, theReply. fname); 
PlotDocHandle**.FileName := theReply. fname; 
PlotDocHandle**.VolRefNum := theReply.vRefNum; 
EnableItem(myMenus[FileM], fSave); 


err := FSClose(refNum); 
IF err © noErr THEN 
BEGIN 


doMessage( ‘Cannot close file...’, '', °’, 4%; 


ExitToShe11; 

END; 
err := FlushVol(NIL, theReply.vRefNum); 
IF err О NoErr THEN 

BEGIN 


doMessage(C'Cannot flush volume...’, °’, '*, '*); 


ExitToShel1; 
END; 


SetCursor Carrow); 
END; (if good) 
END; (else pic exits) 


END; ( of proc) 


PROCEDURE doSave; 
LABEL 


1, 2; 


CONST 


headerBytes = 512; 


TYPE 


VAR 


BEGIN 


DrawHeader = RECORD 
fill: ARRAY[1..256] OF integer; 
END; 


err : OSErr; 

refNum : Integer; 
bytes : LongInt; 
myWindow : WindowPtr; 
title : str255; 

бігі, str2 : str255; 
header : DrewHeader; 
i : integer; 
myPicture : PicHandle; 
PicLength : LongInt; 
myRefNum : integer; 
myFname : str255; 


myPicture :- PlotDocHandle** .Drawing; 
IF myPicture = NIL THEN 


BEGIN 
doMessage( ‘Cannot save file’, ‘Use SaveAs...’, “”, 4%; 

GOTO 1; 
END; 
WITH header DO 

BEGIN 

FOR i := 1 TO headerBytes DIV 2 DO 

filltil] := 0; 
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doMessage( No picture to save yet!’, 9) '’, 492 


myRefNum := PlotDocHandle**.VolRefNum; 
myFname := PlotDocHandle^^.FileName; 
IF myRefNum = 0 THEN 


END; 
bytes := headerBytes; 


err := FSOpen(myFname, myRefNum, refNum); 
IF err € noErr THEN 
BEGIN 
doMessageC'Cannot open file...’, °’, '*, 4%); 
GOTO 1; 
END; 
err := SetFPosCrefNum, FSFromStart, 0); 
IF err  noErr THEN 
BEGIN 


doMessage( ‘Cannot set start of file...', '', '*, 4%; 
GOTO 2; 
END; 


err := FSWriteCrefNum, bytes, @һеадег), 
IF err © noErr THEN 
BEGIN 
doMessage( ‘Cannot write header to file...^, '’’, '^, '’); 
GOTO 2; 
END; 
IF bytes © 512 THEN 
BEGIN 
NumToString(bytes, str1); 
stri := concat(stri, ' bytes’); 
str2 := concatC'out of ', "5127; 
doMessage(‘Only able to write ', stri, str2, ‘to file.’); 
GOTO 2; 
END; 
PicLength := GetHandleSizeCHandle(DrawingPic)); 
bytes := PicLength; 
err := FSWriteCrefNum, bytes, pointer(DrawingPic*)); 
IF err О noErr THEN 
BEGIN 
doMessage( ‘Cannot write picture to file...’, '', °’, (^) 
GOTO 2; 
END; 
IF bytes € PicLength THEN 
BEGIN 
NumToString(bytes, str 1); 
stri := concat(stri, ' bytes’); 
NumToStr ingCPicLength, str2); 
str2 := concatC‘out of ”, str2); 
doMessageC'Only able to write ”, stri, str2, ‘to file.’); 
0070 2; 
END; 


err := FSCloseCrefNum); 

IF err © noErr THEN 
BEGIN 

doMessage( ‘Cannot close file...^, °’, **, 4%); 
ExitToShe11; 
END; 

err := FlushVol(NIL, myRefNum); 

IF err О NoErr THEN 
BEGIN 

doMessage( ‘Cannot flush volume...^, '', '*, 59; 
ExitToShel1; 
END; 


SetCursor Carrow); 
END; (if 9009} 
END; ( of proc) 


END. 


UNIT solve; 
INTERFACE 


USES 
К0М85, PrintTraps, PlotGlobals, Misc; 


PROCEDURE quad (а, b, с: real; 
VAR x1, x2 : real; 
VAR result : integer); 


© The Definitive MacTutor, Vol. 4 


FUNCTION solveit : integer; 
PROCEDURE doP1ot; 
PROCEDURE PrQDStuff CpRect : rect; 
QDdevice : integer); 


IMPLEMENTATION 


FUNCTION positivecalc (а, b, check : real) : real; 


BEGIN 
positivecalc := C-b + sqrt(check)) / (2 * а); 
END; 


FUNCTION negativecalc Ca, b, check : real) : real; 


BEGIN 
negativecalc := (-b - sqrt(check)) / (2 * а); 
END; 


PROCEDURE doDialog; 
VAR 

dialogP : DialogPtr; 
item : integer; 
dtype : integer; 
ditem : handle; 
drect : rect; 
dtext : Str255; 

BEGIN 


dialogP := GetNewDialog(ParamDialog, NIL, pointer(-1)); 


IF dialogP = NIL THEN 
BEGIN 


doMessage( ‘Dialog crash!’, ‘We are dead...’, ‘’, °’); 


ExitToShe11; 
END; 
initCursor; 
IF dialogflg THEN 
BEGIN 
dtext := StringOf(a : 4: 1); 


GetDItemCdialogP, dA, dtype, ditem, drect); 


SetITextCditem, dtext); 
dtext := StringOf(b : 4: 15; 


GetDItemCdialogP, dB, dtype, ditem, drect); 


SetITextCditem, dtext); 
dtext := StringOf(c : 4 : 1); 


GetDItemCdialogP, dC, dtype, ditem, drect); 


SetIText(ditem, dtext); 
dtext := StringOf (step : 5: 3); 


GetDItemCdialogP, dSTEP, dtype, ditem, drect); 


SetITextC(ditem, dtext); 
dtext := StringOf (xscale); 


GetDItemCdialogP, dXSCALE, dtype, ditem, drect); 


SetITextCditem, dtext); 
dtext := StringOf(yscale); 


GetDItemCdialogP, dYSCALE, dtype, ditem, drect); 


SetITextCditem, dtext); 

END; 
REPEAT 

ModalDialog(NIL, item); 
UNTIL item = (ОК; 
GetDItemCdialogP, dA, dtype, ditem, drect); 
GetIText(ditem, dtext); 
ReadString(dtext, a); 
GetDItemCdialogP, dB, dtype, ditem, drect); 
GetIText(ditem, dtext); 
ReadString(dtext, b); 
GetDItemCdialogP, dC, dtype, ditem, drect); 
GetIText(ditem, dtext); 
ReadString(dtext, c2; 
GetDItemCdialogP, dSTEP, dtype, ditem, drect); 
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GetITextCditem, dtext); 
ReadString(dtext, step); 


GetDItemCdialogP, dXSCALE, dtype, ditem, drect); 


GetI TextCditem, dtext); 
ReadString(dtext, xscale); 


GetDItemCdialogP, dYSCALE, dtype, ditem, drect); 


GetIText(ditem, dtext); 
ReadString(dtext, yscale); 
PlotDocHandle**.aParam : 
PlotDocHandle**.bParam : 
PlotDocHandle^^.cParam : 
PlotDocHandle^^.stepPerem := step; 
PlotDocHandle^^.xParam := xscale; 
PlotDocHandle**.yParam := yscale; 
dialogflg := true; 
DisposDialog(dialogP); 

END; 


пи ии 
осо 
we we 


we 


PROCEDURE quad; (Ca, b, с: real;var x1, x2 : real;var 
result : integer );)} 


VAR 
check : real; 
BEGIN 
result := 0; 
check := (b * b) - (4 *а*с); 
IF result = 0 THEN 
BEGIN 
( Check if double root exists } 
IF check = 0 THEN 


BEGIN 
result := 2; 
хі := positivecalcCa, b, check); 
x2 := хі; 

END; 


( Check if real result) 
ІҒ check » 0 THEN 
BEGIN 
result := 1; 
x1 := positivecalcCa, b, check); 
x2 := negativecalc(a, b, check); 
END; 
( Check if root is complex ) 
IF check « 0 THEN 
BEGIN 


check := -check; 
positivecalcCa, b, check); 
negativecalcCa, b, check); 


END; 


PROCEDURE PrQDStuff; ((pRect : rect; QDdevice : integer);) 


CONST 
Display - 1; 
LaserWriter 
ImegeWr iter 
NoJust = 0; 
LeftJust = 1; 
CenterJust = 2; 
RightJust = 3; 
FullJust = 4; 
LinesInParagraph = 5; 
(selected MacDraw comments) 


д 


З, 


picDwgBeg = 130: 
picDwgEnd = 131; 
picGrpBeg = 140; 
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picGrpEnd = 141; 
TextBegin = 150; 
TextEnd = 151; 
StringBegin = 151; 
StringEnd = 153; 
TextCenter = 154; 
(postscript comments) 
SetLineWidth = 182; 
PostScriptBegin = 199; 
TextIsPostscript - 194; 
PostScriptEnd = 191; 
TYPE 
widhdl = ^widptr; 
widptr = ^widpt; 
widpt = Point; 


TTxtPicRec = PACKED RECORD 
tJus : Byte; 
tFlip : Byte; 
tRot : Integer; 
tLine : Byte; 
tOmnt : Byte; 
END; 


VAR 


le, tp, ri, bo : integer; 


stri, str2, str3, str4, str5 : str255; 


str6, str7, str8, str9 
hPos, vPos, hor, ver 
X, у, 21, z2 : real; 
rBox, ClipBox : rect; 
Width : Widhd!; 
leading : integer; 
LineNo : integer; 
ParagraphBegin : Point; 
Indent : integer; 


: Str255; 
: integer; 


Paragraph : ARRAYL1..LinesInParegreph] OF str255; 


TxtPicRec : TTxtPicRec; 
TxtPicPtr : QDPtr; 
TxtPicHd] : QDHandle; 
TextClipRgn : RgnHendle; 
SaveClip : RgnHandle; 
fInfo : FontInfo; 


BEGIN 
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SaveClip :- NewRgn; 

GetClip(SaveClip); 

ClipRect(pRect); 

TextClipRgn := NewRgn; 

penNormal; 

IF QDdevice = LaserWriter THEN 
BEGIN 


TextFont(times); 

TextSize(10); 

TextFace([]); 

TextModeCsrcOr 2; 

END; 

hor := (pRect.right - pRect. left) DIV 2; 
ver := C(pRect.bottom - pRect.top) DIV 2; 
Width := WidhdlCNewHandleCsizeof (widpt))); 
Width^^.h := 10; 
Width^^.v := 1; 
TxtPicPtr := eTxtPicRec; 


TxtPicHdl := eTxtPicPtr; 
TxtPicRec.tJus := LeftJust; 
TxtPicRec.tFlip := 8; (no flip) 
TxtPicRec.tRot := 8; (no rotation) 
TxtPicRec.tLine := 2; (1 1/2 spacing) 


GetFontInfoCf Info); 


leading := fInfo 
Indent := 2; 

x := -xscale / 2 
y:=a*x*x + 
hPos := integer( 


.descent + fInfo.ascent + fInfo. leading; 


(b * x) + c; 
round(x * hor * 2 / xscale + hor)); 


integerCround(-y * ver * 2 / yscale + ver)); 


zi := -b / (2 * a); 
z2 := (4% a *c- (b * b) / (4 за); 
le := 2; 
tp := ver + (ver DIV 3); 
ri := 140; 
IF ri >= Chor + hor DIV 3) THEN 
ri := hor + hor DIV 3; 


bo := ver + ver - 2; 


setRect(rBox, le 
ParagraphBegin.h 


ParagraphBegin.v : 


(Graph Text) 


stri := stringOf 
str2 := stringOf 
str3 :» stringOf 
str4 := stringOf 
Peregreph[1] := 
Peregreph[2] := 


EL fy uu КЕ? 


Paragraph[3] := 


: 5 : 3, chrC 1355; 


CASE result OF 


, tp - 14, ri, bo); 


9 


ір; 


(-xscale DIV 2); 
(yscale DIV 2); 
(xscale DIV 2); 
(-yscale DIV 2); 


StringOf('ysex^2 + bx + с’, chr(13)); 

StringofC'ez^, а: 3 : 1, ', b=” b:3 
chr 132); 

StringOf C'x12^, x1: 5 : 3, ', x2=”, x2 


1: 
Paragraph(4] := StringOfC'Two Real Roots, x1, x2’, chr(13)); 
2 . 


Peregreph[4] := StringOfC'Double Root’, chr(13)); 
3 . 


Регадгарн [4 ] 


OTHERWISE 


д 


END; 


:z StringOfC'Two Complex Roots ”, сһг(13)); 


Peregrephí5] := StringOfC'Slope 0 = С“, 21:2: 1, '^,z2: 


2: 


1, 92”, chr(13)); 
PenNormal; 
BackColor (Color [ 
ForeColor (Color [ 


(Drawing Boundry 


BackgroundColor 1); 
Ахізбо1ог 1); 


) 


PicComment(picDwgBeg, 0, NIL); (Begin MacDraw Document) 
Р1сСоттеп{ (р1сбгрВед, 0, NIL); 
PicComment(SetLineWidth, 2, Handle(Width)); 


IF 00деуісе - Di 


spley THEN 


FillRectCpRect, white); 


FremeRectCpRect) 


(Two Axis) 


д 


PicComment(picGrpBeg, 0, NIL); 


moveto(0, ver); 


lineChor * hor, 0); 


movetoChor, 0); 


line(Q, ver + ver); 
PicComment(picGrpEnd, 0, NIL); 


ForeColor(CColor [GraphColor 1); 


(Plot Itsef) 


PicComment(picGrpBeg, 0, NIL); 
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movetoChPos, vPos); 

REPEAT 

X :* X + Step; 

у= а*х*х+ (b * x) t c; 


hPos := integer(round(x * hor * 2 / xscale + hor)); 
:= integer(round(-u * ver * 2 / uscale + ver)); 


vPos 
WITH pRect DO 


IF (hPos < right) AND (hPos > left) AND (vPos < 


bottom) AND (vPos > top) THEN 
LineTo(hPos, vPos) 
ELSE 
moveto(hPos, vPos); 

UNTIL x >= xscale / 2; 
PicComment(picGrpEnd, 0, NIL); 
ForeColor(Color[1]); 
(Axis Text) 
moveto(4, ver + 14); 
DrawString(str1); 
moveto(hor - 40, 14); 
DrawString(str2); 
moveto(hor + hor - 50, ver + 14); 
DrawString(str3); 
moveto(hor - 40, ver + ver - 14); 
DrawString(str4); 
(Box ) 
PicComment(picGrpBeg, 0, NIL); 
PicComment(picGrpBeg, 0, NIL); 
PicComment(SetLineWidth, 2, Handle(Width)); 
IF QDdevice = Display THEN 

fillRect(rBox, white); 
frameRect(rBox); 
PicComment(picGrpEnd, 0, NIL); (of box) 


GetClip(TextC1ipRgn); 
ClipBox := rBox; 
ClipRectCC1ipBox2; 
(Box Text) 


PicComment(TextBegin, sizeof(TTxtPicRec), Handle(TxtPicHd1)); 


FOR LineNo := 1 TQ LinesInParagraph 00 
BEGIN 


moveto(ParagraphBegin.h, ParagraphBegin.v); 


moveCIndent, CLineNo - 1) * leading); 
DrawS tr ing(Paragraph [| ineNo1); 
END; 
PicComment(TextEnd, 0, NIL); 
PicComment(PicGrpEnd, 0, NIL); {of Box & text} 


PicComment(PicGrpEnd, 0, NIL); (of select 811 objects) 


picComment(picDwgEnd, 0, NIL); {of drawing) 
SetClip(SaveClip); 
disposHandle(handle(width)); 
бісрозеКоп(ТехіСТ ірЕап); 
DisposeRgn(SaveClip); 

END; 


PROCEDURE PlotMe; 
CONST 
Display = 1; 
VAR 
Displayrect : rect; 
pstate : PenState; 
BEGIN 
Displayrect := PicRect; 
IF PlotDocHandle**.drawing € NIL THEN 
BEGIN 
Kil 1Picture(DrawingPic); 
PlotDocHandle^^.drawing := NIL; 
END; 
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GetPenStateCpstate); 

DrawingPic := OpenPicture(Displayrect); 

PrQDStuffCDispleyrect, Display); 

ClosePicture; 

SetPenState(pstate); 

InvalRect(Displayrect); (drew picture) 

PlotDocHandle^^.drewing := DrawingPic; (save it) 
END; 


FUNCTION solveit; ( : integer;) 
BEGIN 
doDialog; 
IF a © Ø THEN 
quad(a, b, с, x1, x2, result) 


result := -1; 
solveit := result; 
END; 


PROCEDURE doPlot; 
BEGIN 
result := solveit; 
showWindowCPlotWindow2; 
IF PlotWindow <> FrontWindow THEN 
SelectWindowCPlotWindow); 
IF result © -1 THEN 
BEGIN 
PlotMe; 
EnableItem(nyMenus[FileM], fPrint); 
END; 


UNIT MyPr intStuff ; 
INTERFACE 


USES 


К0М85, PrintTreps, PlotGlobals, Misc, myFileStuff, Solve; 


PROCEDURE doPageSet; 
PROCEDURE doPr int ; 


IMPLEMENTATION 


PROCEDURE Pr intMe; 
CONST 
LaserWriter = 2; 
VAR 
theWorld : rect; 
pstate : penstate; 
BEGIN 
theWorld := PicRect; 
IF Option = 1 THEN 
theWorld := PicRect 
ELSE IF Option = 2 THEN 
theWorld := PageRect 
ELSE 


doMessage( ‘Printing Rectangle Problem’, ‘’, '', “42; 


GetPenState(pstate); 
PrintingPic := OpenPicture( theWorld); 
PrQDStuff CtheWorld, LaserWriter); 
ClosePicture; 
SetPenState(pstate); 
DrewPictureCPrintingPic, theWorld); 
KillPictureCPrintingPic2; 

END; 


PROCEDURE doPr int; 
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VAR 
DoIt : boolean; 
myPrint : THPrint; 
myPrStatus : TPrStatus; 
myPrPort : TPPrPort; 
PrRect : rect; 
stri : str255; 
temp : GrafPtr; 
numCopies : integer; 
count : integer; 
prStatus : TPrStatus; 


BEGIN (1) 
IF DrewingPic © NIL THEN 

BEGIN (2) 
myPrint := PlotDocHandle^*^.print; 
getport( temp); 
PrOpen; 
IF PrError = noErr THEN 

BEGIN (3) 


DoIt := PrValidateCmyPrint); 
DoIt := PrJobDialog(myPr int); 
IF PrError © noErr THEN 
doMessage( ‘Printer error in job dialog’, '', '', 4%; 
IF DoIt THEN 
BEGIN (4) 
myPrPort := PrOpenDoc(myPrint, NIL, NIL); 
IF PrError = noErr THEN 
BEGIN (5) 
numCopies := myPrint^^.prJob. iCopies; 
FOR count := 1 TO numCopies 00 
BEGIN (6) 
PrOpenPage(myPrPort, NIL); 
ІҒ PrError - noErr THEN 
BEGIN (7) 
( print something dumny!) 
PegeRect := myPrint^^.prInfo.rPage; 
PrintMe; 
END ( 7) 
ELSE 


doMessage( ‘OpenPage error’, “cannot print this раде’, '', 49; 


PrClosePage(myPrPor t ); 
IF PrError © noErr THEN 


doMessage( ‘ClosePage error’, ‘cannot close this page’, °’, 


77). 
д 


END; (6) 
END ( 5) 
ELSE 


doMessage(‘OpenDoc error’, ‘cannot print’, °’, 42; 


PrCloseDoc(CmyPrPor t); 
IF PrError © noErr THEN 
doMessage(‘CloseDoc error’, ‘’, °’, 4%); 


myPrint := PlotDocHandle** .print; 
PrOpen; 
IF РгЕггог = noErr THEN 
BEGIN 
DoIt := PrValidateCmyPrint); 
DoIt := PrStiDialog(ngPr int); 
IF PrError © noErr THEN 
doMessage('Printer error in style dialog’, '', '*, '") 
ELSE 
PageRect := myPrint^^.prInfo.rpage; 
END 
ELSE 
doMessage( ‘Cannot perform PrOpen!’, '', °’, 42; 
PrClose; 


END; 
END. (of unit) 


UNIT PlotGlobals; 
INTERFACE 
USES 
К0М85, PrintTraps; 
( Global Constants ) 
CONST 


(nultifinder stuff) 
SysEnvTrep = $90; 
WNETrapNum = $60; (trep number of WaitNextEvent) 
UnImplTrapNum = $9F; (trap number"unimplemented trap”) 
(window constants) 
ZoomBox = 8; (window type) 
MinWidth = 80; 
MinHeight = 80; 
mBarHeightGlobal = $ВАА; 
GrayRgnLowMemGlobal = $9EE; 
sBarWidth = 16; 
rsrc = 'PLTR^; (creator bytes restype) 
(dialog stuff) 
AboutDialog = 256; 
PeramDialog = 257; 
MessageDialog = 258; 
AlertDialog = 260; 
( menu res id's) 
AppleMenu = 256; 
FileMenu = 257; 
EditMenu = 258; 
ColorMenu = 259; 
OptionMenu = 260; 
(submenus 1975) 
GraphMenu = 44; 
AxisMenu = 45; 
BackgroundMenu = 46; 


IF (myPrint**.prdob.bUDocLoop = bSpoolLoop) 


AND CPrError = поегг) THEN 


PrPicFileCmyPrint, NIL, NIL, NIL, prStatus); 
END; (4) 
END; (3) 
PrClose; 
setport(temp); 
END; (2) 


END; (of proc 1) 


PROCEDURE doPageSet; 


VAR 
DoIt : boolean; 
myPrint : THPrint; 


BEGIN 
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MenuCount = 5; 
SubMenuStart = 6; 
TotalMenuCount = 8; 


AppleM - 1; 
FileM = 2; 
EditM = 3; 
ColorM = 4; 
OptionM = 5; 
Graph = 6; 
Ах1$М = 7; 


BackGroundM = 8; 


(menu items) 


eAbout = 1; 
fPlot = 1; 
fSave = 3; 
fSaveAs = 4; 
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fPageSet = 5; GrowArea : Rect; (window grow aree) 


fPrint = 6; Screen : Rect; (physical screen area) 

fQuit = 8; PlotWindowRect : Rect; (beginning window size) 
eUndo = 1; ZoomRect : Rect;  (zoomed window size) 

eCut = 3; HCRect, VCRect, GrowRect : Rect; (scroller rects) 
eCopy - 4; PicRect : Rect; (content region of less scrollers) 
ePeste - 5; PageRect : rect; 


eClear = 6; 

oWindowRect = 1; 

oPageRect = 2; 
(Dialog Items) 


(dialogs stuff) 
ItemHit : integer; 
dialogflg : boolean; 
(plot stuff) 


dOK = 1; 8, b, c, x1, x2, check, step : real; 
dA = 2; result, xscale, yscale : integer; 
dB = 3; PlotWindow : WindowPtr; 
dC = 4; PlotWindowPeek : WindowPeek; 
dSTEP = 5; PlotDocHandle : DocHandle; 
dXSCALE - 6; DrewingPic : PicHandle; 
dYSCALE = 7; PrintingPic : PicHandle; 
TYPE 

Document = RECORD IMPLEMENTATION 

aParam : real; 

bParam : real; END. 

cParam : real; 

stepParam : real; UNIT Misc; 

xParam : integer; 

yParam : integer; INTERFACE 


drawing : PicHandle; 9 
print : THPrint; 
FileName : str255; ROM85, PrintTraps, PlotGlobals; 


YOURE емс integer; PROCEDURE doMessage (messaged : str255; 


END; messagel : str255; 
DocPtr = “Document, message2 : str255; 
DocHandle = ^DocPtr; message3 : str255); 
LongAndByte - RECORD 
CASE integer OF IMPLEMENTATION 
кк longView : LongInt PROCEDURE doMessage; ((теззадей : str255) 
): (message! : str255) 
е ieee 2. 
i n і 
byteView : RECORD VAR ыды 
byte® : SignedByte; dialogP : DialogPtr; 
bytel : Signedbyte; item : integer; 
byte2 : Signedbyte; BEGIN 
byte3 : Signedbyte; РагатТех((пе5580е0, messagel, message2, message3); 
END; T. dialogP := GetNewDialog(MessageDialog, NIL, pointer(- 
T ; IF dialogP = NIL THEN 
7 
( Global Variables ) mé tS 
VAR ExitToShe11; 
(ny misc stuff) END; 
Finished : boolean; initCursor; (change to arrow) 
mBarHeight : Integer; Moda IDi&log(NIL, item); 
(Multifinder stuff) DisposDialog(dialogP); 


НМЕ : boolean; (Multifinder friendly) END; 
SysEnv : boolean; (Multifinder friendly) 


theWorld : SysEnvRec; (not in LSP 1.11 ) END. 
typeOfMac : integer; š 
mouseRgn : RgnHandle; (cursor region to pass to WNE) sewer СК 


(menu stuff} 

myMenus : ARRAY[1..TotalMenuCount] OF MenuHandle; 

GraphColor : integer; 

AxisColor : integer; 

BackgroundColor : integer; 

color : ARRAY[1..8] OF LongInt; 

Option : integer; (1 = windowrect, 2=pagerect} 
(rectangles) 

ОгадАгеа : Rect; (window drag area) 


Plotter .RSRC 
277777927 


Туре PLTR = STR 


д 
9 by Dave Kelly & Dave Smith 10Оуег 4 JAN 1988 
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Туре ҒКЕР Color Plot Demo\@D\@D++ 


, 128 Graph /\1B!\2C Graphs Quadratic Equations\@D°8\8D* 11007210073 
APPL @ Axis /\1B!\2D 
, 129 Background /\1B!\2E Ріс ет Disabled 
PICT 1 10 10 96 81 
* the Option menu 128 


Туре BNDL ,260 
, 128 Print Options * Plot box dialog... 
PLTR 0 Window Size /[ type DLOG 
ІСМЕ Page Size /] ‚257 
0 128 1 129 Plot Parameters 
FREF * submenus 100 105 250 405 
0 128 1 129 ‚44 Visible NoGoAway 
Graph 4 
.* — Multifinder events —— Black 0 
White 251 
* bit 15 = switcher save screen Red 
* bit 14 = accept suspend resume events Green type DITL 
* bit 13 = switcher enable option switch Blue ‚257 
* bit 12 = сап do background оп null events Cyan 13 
* bit 11 = multifinder aware Magenta * ok button (default) 
x (activates & deactivates topmost Yellow BtnItem Enabled 
x window at resume, suspend events) 110 230 136 275 
,45 OK 
Туре SIZE = GNRL Axis 
y*1 Black * & parameter 
Н White EditText Enabled 
4800 ;; $4800 - bits 14,11 set Red 30 15 46 60 
¿L Green 1 
128000 ;; (Гог 150К recomended) Blue 
L Cyan * b parameter 
80000 ;; (Гог 80К minimum) Magenta EditText Enabled 
.I Yellow 30 100 46 145 
* menus = 
‚46 
Туре MENU Background *c paremeter 
* the desk acc menu Black EditText Enabled 
,256 White 30 180 46 225 
\14 ;¿;apple menu Red -6 
About Plotter... Green 
(- Blue * step parameter 
Cyan EditText Enabled 
* the file menu Magenta 80 10 96 65 
‚257 Yellow ‚05 
File 
Plot /P ж xscale parameter 
(- x — Dialogs --- EditText Enebled 
(Seve /5 * About Box dialog... 80 100 96 150 
Зауе 85.. {уре 0106 10 
Page Setup.. /U ,256 
(Print... /0 About Plotter... * yscale parameter 
(- 100 100 250 400 EditText Enabled 
Quit /Q visible NoGoAway 80 185 96 235 
1 20 
* the edit menu 0 
,258 256 StatText Disabled 
Edit 10 35 26 55 
(Undo /Z type DITL а 
(= ‚256 
Cut /X 3 StatText Disabled 
Copy /C BtnItem Enabled 10 120 26 140 
Paste /V 112 235 141 284 b 
Clear | OK 


StatText Disabled 
* the color menu StatText Disabled 10 200 26 220 
,259 10 88 141 289 с 
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StatText Disabled 
60 10 76 65 
step size 


StatText Disabled 
60 95 76 150 
x scale 


StatText Disabled 
60 180 76 250 
u scale 


* Program Messages Dialog box... 
type DLOG 
, 208 
Program Messages 
100 100 200 400 
Visible NoGoAway 
1 
0 
258 


{уре DITL 

,258 
3 
BtnItem Enabled 
65 230 95 285 
OK 


StatText Disabled 
15 68 85 222 
701007 11007210073 


IconItem Disabled 


10 10 42 42 
1 


* —— Alerts 


* Program error alerts... 
type ALRT 
‚ 260 
100 100 200 400 
260 
5555 


type DITL 
,260 
2 


BtnItem 
65 230 95 285 
OK 


StatText Disabled 
15 60 60 275 
Program Problem АЛегі:(0070714273 


* misc resources 


Туре ICN® = GNRL 
, 128 (0) 
.H 
0001 0000 0002 8000 0004 4000 0008 2000 
0010 1000 0020 0800 0050 0400 0088 0200 
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0100 0100 0284 0080 0440 0240 0822 0420 
1410 0810 220A 1008 4084 3Ғ04 802A 4082 
4001 8041 2003 3022 1005 C814 080Е ТЕВЕ 
0412 3005 0221 0007 0140 8005 0080 6007 
0040 1ҒЕБ 0020 021Ғ 0010 0407 0008 0800 
0004 1000 0002 2000 0001 4000 0000 8000 
Ж 

0001 0000 0003 8000 0007 С000 000Ғ Е000 
001Е Ғ000 003Ғ Ғ800 007Ғ ЕС00 @0ЕЕ ҒЕ00 
ЙІҒЕ FF00 O3FF ҒҒ80 O7FF ЕЕС OFFF FFEO 
IFFF FFFÜ 3FFF FFFB 7FFF FFFC FFFF FFFE 
TFFF FFFF 3FFF FFFE IFFF FFFC ØFFF FFFF 
@ТЕЕ FFFF 0ЗЕЕ FFFF @1ЕР FFFF ØØFF FFFF 
OO7F FFFF ØØ3F FEIF 0012 FC07 GOOF Ғ800 
0007 Ғ000 0003 Е000 0001 С000. 0000 8000 


Туре ICN* = GNRL 
‚ 129 (0) 


.H 

ЙҒҒҒ ҒЕ00 0800 0300 0800 0280 0800 0240 
0800 0220 0800 0210 0800 03Ғ8 0801 0008 
0880 0008 0801 0208 0840 0008 0801 0408 
0820 0008 0801 0808 0810 0008 0801 1008 
0AAB AAAB 0809 2008 0804 4008 0803 8008 
0800 0008 0801 0008 0800 0008 0801 0008 
0800 0008 0801 0008 0800 0008 0801 0008 
0800 0008 0800 0008 0800 0008 OFFF ҒҒҒ8 
x 


OFFF ҒЕ00 OFFF FFOO OFFF ЕҒ80 OFFF FFCO 
OFFF FFE OFFF FFFO OFFF FFF8 OFFE FFF8 
OF7F FFF8 OFFE ҒОҒ8 OFBF FFF8 OFFF FBF8 
OFDD 7FF8 OFFA B7F8 ØFE7 DFFB OFEF FFFB 
0074 5058 OFB7 DBF8 ØF7B BDFB @EFD 7EF8 
OFFF FFFB OFFF FFF8 ØFFF FFFB OFFF FFFB 
OFFF FFFB OFFF FFF8 OFFF FFF8 OFFF FFFB 
OFFF FFFB OFFF FFFB FFF FFF8 OFFF FFF8 


TYPE PICT = GNRL 

, 128 
m 
891 
195 254 281 325 
‚Н 
1101 А000 82А0 008Е 0100 0А00 0000 0002 
0002 4098 000A 00C3 00-8 OOFF 0148 00С3 
00ҒЕ ØØFF 0145 00С3 00ҒЕ BOFF 0145 0000 
62-7 0002 Ғ100 02Ғ7 0002 Ғ700 02Ғ7 0002 
F700 02Ғ7 0002 Ғ700 02Ғ7 0002 Ғ700 02Ғ7 
0006 Ғ000 000Е ҒС00 B7FD 0001 1-80 Ғ000 
@TFD 0001 TFCO FDOO 07FD 0001 FFFO Ғ000 
08ҒЕ 0002 O3FF FCFD 0008 ҒЕ00 0207 FFFE 
Ғ000 09ҒЕ 0003 1FFF FF80 ҒЕ00 OO9FE 0003 
SFFF ҒҒЕй FEJØ 29FE 0003 ТЕРЕ FFF8 ҒЕ00 
0А02 0000 OIFE ҒҒ00 FCFE 0008 0200 0003 
ГОРЕ ҒЕ00 0А02 0000 OFFD FFOO COFF 0008 
0700 00ІҒ FFFF ЗҒҒҒ EOFF 0008 0700 007Ғ 
FFFE 1FFF F8FF 0008 0700 OOFF FFFE IFFF 
FCFF 0008 0100 0ІҒЕ ҒҒ02 27FF ЕСЕР 0008 
0100 O1FE FF02 ҒОҒҒ F8FF 0008 0100 00ҒЕ 
FF02 ҒЕТЕ FOFF 000В 0200 003Ғ FEFF 019Ғ 
ЕВЕЕ 0008 0200 001Е FEFF 01Е7 COFF 0008 
0200 003Ғ FEFF 01Ғ9 80ҒҒ 0008 0200 0033 
FEFF 01ҒЕ 80ҒҒ 000А 0200 0060 FDFF 00С0 
ҒҒ00 0807 0000 6O7F FFFF FCCO ҒҒ00 0807 
0000 601F FFFF F870 ҒҒ00 0807 0000 6007 


FFFF FOF8 ҒҒ00 0807 0000 6001 FFFF FOF8 
FF00 0807 0000 6000 FFFF FOFB ҒҒ00 0807 
0000 6038 ЭҒҒҒ В050 ҒҒ00 0А06 0000 607С 
OFFF 30ҒЕ 0008 0700 0060 Ғ603 FE30 ABFF 
0008 0700 0060 E301 FC30 50ҒЕ 0008 0700 
0060 С000 7830 20ҒҒ 0008 0700 0060 0000 
1030 88FF 0008 0200 0060 ҒЕ00 0130 SOFF 
000А 0200 0060 ҒЕ00 0030 ҒЕ00 0802 0000 
60ҒЕ 0001 30А8 ҒҒ0 0807 0000 6807 0700 
В050 ҒҒ00 0А06 0000 681F BFCO BOFE 0008 
0700 006С TFDF Ғ180 ABFF 000А 0200 0067 
FEFF 0030 ҒЕ00 0809 0000 63FF FFFE 31F4 
1000 0809 0000 307F DFFØ 6046 3000 0809 
0000 381F 8ҒС0 Е045 5000 0809 0000 1С00 
0001 С044 9000 0809 0000 0-00 0003 8044 
1000 0802 0000 ОТҒЕ FFFD 0009 0500 0001! 
FFFF FCFD 0008 ҒЕ00 0280 0004 Ғ000 9800 
0А00 FFOO Ғ801 1901 4800 ҒҒ00 ҒЕ01 1901 
4500 FF00 FEB! 1901 4500 0008 ҒЕ00 0280 
0004 Ғ000 08ҒЕ 0002 FFFF FCFD 0008 0200 
0001 FEAA Ғ000 0802 0000 ОЗЕЕ 55FD 000А 
0600 0006 FEAF ЕА80 ҒЕ00 0А06 0000 0083 
5835 40ҒЕ 000A 0600 0018 0180 1ЛА0 FEJ 
0А06 0000 3501 5015 50ҒЕ 000A 0600 006A 
8248 2AAB ҒЕ00 0А06 0000 0570 5707 Ғ4ҒЕ 
000А 0600 O1AF ААҒА ACIA ҒЕ00 0А06 0003 
5055 0558 ØDFE 0008 0700 06AO 2402 ABA 
BÜFF 0008 0700 0060 3603 5415 40ЕҒ 0008 
0700 0А80 6806 ABEA COFF 0008 0700 005Ғ 
0520 5555 40FF 0009 0100 ФАРС АА00 COFF 
0009 0100 00ҒС 5500 40ҒҒ 0009 0100 OFFC 
FF00 COFF 0002 Ғ700 02Ғ7 0002 Ғ700 02Ғ7 
0002 Ғ700 02Ғ7 0002 Ғ700 А000 BFAD 0083 
FF 


* Menu color Def initions 

x 

х TYPE mctb followed by 10%, 
* followed by number of entries. 
* (10 0 is menu ber entry.) 

ж Other 108 are menu 108. 

x 

* For each entry: 

* 1. Menu ID number 

* 2. Menu item number 

* 3. R6B color 1 (3 INTEGERS) 
* 4. RGB color 2 (3 INTEGERS) 
* 5, R6B color 3 C3 INTEGERS) 
* 6. R6B color 4 (3 INTEGERS) 
* 7. filler integer 


* menu bar 
Туре mctb = GNRL 


* number of entries 

‚1 

1 

al 

* Menu ID number & the Menu item number 
* Q & @ for menu bar entry. 

* Default title & title background = 
* black on white 

* Default item & item background = 

* magenta on white 

020 
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.H 
0000 0000 0000 
FFFF FFFF FFFF 
FFFF 0000 FFFF 
FFFF FFFF FFFF 
0000 


* apple menu 
‚256 
9: 
3 
.I 
* title & title background = 
* Cyan on white 
* defeult item & backgrounds 
* red on white 
256 0 
‚Н 
0000 FFFF FFFF 
FFFF FFFF FFFF 
FFFF 0000 0000 
FFFF FFFF FFFF 
0000 
.I 
* [TEM ONE 
* Mark, command, name 
* and background = 
* blue on white 
256 1 
‚Н 
0000 0000 FFFF 
0000 0000 ҒҒҒҒ 
0000 0000 FFFF 
FFFF FFFF FFFF 
0000 
‚1 
ж [TEM TWO 
* Mark, command, name 
* and background = 
* blue on white 
256 2 
.H 
0000 0000 FFFF 
0000 0000 FFFF 
0000 0000 FFFF 
FFFF FFFF FFFF 
0000 


* Graph menu 

,44 
41 
8 
9! 
* black on white 
44 1 
‚Н 
0000 0000 0000 
0000 0000 0000 
0000 0000 0000 
FFFF FFFF FFFF 
0000 
41 
* black on white 
44 2 
.H 
0000 0000 0000 


294 


0000 0000 0000 
0000 0000 0000 
FFFF FFFF FFFF 
0000 

‚1 
* red on white 
44 3 

‚Н 
FFFF 0000 0000 
FFFF 0000 0000 
ҒҒҒҒ 0000 0000 
FFFF FFFF FFFF 
0000 

I 


* green on white 


44 4 

‚Н 

0000 FFFF 0000 
0000 FFFF 0000 
0000 FFFF 0000 
FFFF FFFF FFFF 
0000 

‚1 

* blue on white 
44 5 

‚Н 

0000 0000 FFFF 
0000 0000 FFFF 
0000 0000 FFFF 
FFFF FFFF FFFF 
0000 

.I 

* cyan on white 
44 6 

‚Н 

0000 FFFF FFFF 
0000 FFFF FFFF 
0000 FFFF FFFF 
FFFF FFFF FFFF 
0000 

4 


* magenta on white 


44 1 

„Н 
FFFF 0000 FFFF 
FFFF 0000 FFFF 
FFFF 0000 FFFF 
FFFF FFFF FFFF 
0000 

I 


* yellow on white 


44 8 
.H 

FFFF FFFF 0000 
FFFF FFFF 0000 
FFFF FFFF 0000 
FFFF FFFF FFFF 
0000 


* Axis menu 
‚© 

al 

8 

‚1 

45 1 

‚Н 

0000 0000 0000 


0000 0000 0000 
0000 0000 0000 
FFFF FFFF FFFF 
0000 

4 

45 2 
H 

0000 0000 0000 
0000 0000 0000 
0000 0000 0000 
FFFF FFFF FFFF 
0000 

1 

45 3 

‚Н 

FFFF 0000 0000 
FFFF 0000 0000 
FFFF 0000 0000 
FFFF FFFF FFFF 
0000 

4 

45 4 

H 

0000 FFFF 0000 
0000 FFFF 0000 
0000 РЕЕЕ 0000 
FFFF FFFF FFFF 
0000 

4 

45 5 

H 

0000 0000 FFFF 
0000 0000 FFFF 
0000 0000 FFFF 
FFFF FFFF FFFF 
0000 

4 

45 6 
.H 

0000 FFFF FFFF 
0000 FFFF FFFF 
0000 FFFF FFFF 
FFFF FFFF FFFF 
0000 

1 

45 7 

.H 

FFFF 0000 FFFF 
FFFF 0000 FFFF 
FFFF 0000 FFFF 
FFFF FFFF FFFF 
0000 

4 

45 8 

H 

FFFF FFFF 0000 
FFFF FFFF 0000 
FFFF FFFF 0000 
FFFF FFFF FFFF 
0000 


* Background menu 


,46 
.I 
8 
.I 


0000 0000 0000 
0000 0000 0000 
0000 0000 0000 
FFFF FFFF FFFF 


0000 0000 0000 
0000 0000 0000 
0000 0000 0000 
FFFF FFFF FFFF 


FFFF 0000 0000 
FFFF 0000 0000 
FFFF 0000 0000 
FFFF FFFF FFFF 


0000 FFFF 0000 
0000 FFFF 0000 
0000 FFFF 0000 
FFFF FFFF FFFF 


.I 
46 5 
‚Н 

0000 0000 РЕРЕ 
0000 0000 FFFF 
0000 0000 FFFF 
FFFF FFFF FFFF 
0000 

.I 

46 6 

.H | 

0000 FFFF FFFF 
0000 FFFF FFFF 
0000 FFFF FFFF 
FFFF FFFF FFFF 
0000 

.I 

46 7 

.H 

FFFF 0000 FFFF 
FFFF 0000 FFFF 
FFFF 0000 FFFF 
FFFF FFFF FFFF 
0000 

J 

46 8 

FFFF FFFF 0000 
FFFF FFFF 0000 
FFFF FFFF 0000 
FFFF FFFF FFFF 
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Macintosh П 


Screen Dump FKEY for Color Picts ` 


In our first article, we saw how to create a plot in PICT 
format, complete with the old style Quickdraw color. But, since 
our program did not include an open command, how can we view 
the plot in color once it is made? If we try to snapshot the color 
screen, we get a beep! What we need is a way to snapshot and 
view our plot without having to turn off the color. Steve Sheets, 
from Apple's Chicago technical support office, shows us how to 
capture the screen on a Mac II with the color enabled.And best 
of all, the picture is not rotated! Once we capture our plot, we 
want to view it. Steve again comes to our rescue with a compan- 
ion viewer DA for color PICTs. 


Color Images: Saving and Loading 

Since this column has given some examples of how to draw 
in Color on the Mac //, now would be a good time to describe how 
to save and load color pictures. While a specific file format can 
always be defined for an application, it is convenient to be able 
toread generic file formats, so that various applications can share 
and port data. When discussing graphics, the two generic file 
formats have always been MacPaint file format and PICT file 
format. MacPaint format has always been considered the generic 
Bitmap method of saving Mac graphics, while PICT format is the 
associated with object oriented graphics programs (ie. 
MacDraw). 

With the introduction of Color Quickdraw and the Mac //, 
things have changed slightly. Unfortunately MacPaint file 
format can not be expanded to cover PixMap graphics (ie. 
multiple colors per pixel). Nor is there any other PixMap file 
format that has been widely accepted by developers (though 
there is a need). On the other hand, PICT file format is nothing 
but an extension of a Quickdraw Picture Handle. With the 
introduction of the Mac //, Quickdraw Pictures have been ex- 
panded to support color. This article will talk about the new 
Color Quickdraw Picture format, the PICT file format, and will 
touch briefly on using the Palette Manager to display a Picture in 
the Color needed. The example sources, ColorImage DA and 
ColorImage ЕКЕҮ, will demonstrate how to save and read PICT 
file. 


Quickdraw Picture Format 

A Quickdraw Picture is a data structure that contains a 
sequence of Quickdraw commands. То create a Picture, a 
program defines a Picture Frame (ie, a rectangle and data struc- 
ture) with the OpenPicture function. OpenPicture returns a 
handle to the Picture data structure being created. At this point, 
the program can call any Quickdraw command. Instead of being 
drawn on the current grafport, the command is stored in the 
Picture forlater use. A ClosePicture command needs to be issued 


© The Definitive MacTutor, Vol. 4 


Steven C. Sheets 
Chicago, IL 
MacTutor Vol. 4 No. 2 


to tell Quickdraw to stop saving the commands into the Picture 
Handle. Once the program has a Picture, it can display it using 
the DrawPicture call. This will draw the Picture (ie. all the 
Quickdraw commands saved in the Picture) into a destination 
rectangle. If the destination rectangle is not the same size as the 
picture frame, the picture will be expanded or reduced to fit the 
destination rectangle. The Plotter program in this issue illustrates 
this traditional use of the Quickdraw picture. 

The Picture handle points to a data structure which contains 
the Picture Size (Integer picSize), the Picture Frame (Rect 
picFrame) and various Opcodes describing the Quickdraw calls. 
Always ignore picSize. With the expansion of the Memory 
Manager so that it can handle sizes beyond 32K, picSize is now 
ignored by Quickdraw. Instead, the picture is played out until the 
end. If the Picture size is needed, call GetHandleSize. Generally 
beyond picSize and picFrame, a program should not read the data 
structures directly. The internal structures beyond this point are 
documented in Inside Macintosh, Vol 5 and the various tech notes 
cited in the Pascal column. 

Animage stored and drawn as aPicture (using DrawPicture) 
is much more compressed than the same image drawn using 
individual Quickdraw commands in the code. Also the program 
can pass a Picture through the clipboard and Scrapbook to other 
Applications. Notice while the Picture is considered an Object 
Graphic type of data structure, one of the commands it stores is 
CopyBits. A Picture can thus have BitMapped graphics in it. 


Version 1 vs Version 2 Format 

With the introduction of the Mac //, the Picture Format has 
been extended. The old Picture format (called Version 1 Format) 
contains only the non-Color Quickdraw commands. The newer 
Picture format (called Version 2 Format) contains all the Color 
Quickdraw commands. On a Mac //, which Format is created 
with an OpenPicture call depends on the current GrafPort. If an 
OpenPicture call is made when the current GrafPort is a Color 
GrafPort, the Picture created is a Version 2 format. If a call is 
made on a normal GrafPort, a Version 1 Picture is created. 
Obviously non-Mac // computers can not create a Version 2 
Picture. However, due to a patch in System 4.1 and later, an 
Enhanced Mac 512K, a MacPlus or a Mac SE can display a 
Version 2 Picture (not in color, of course). 

While checking the Opcodes (Quickdraw picture com- 
mands) directly is not a good idea, a program can identify which 
version of Picture it has by checking the first integer past the 
picSize and picFrame. If this integer is 4353 ($1101), the Picture 
is Vers. 1. If the integer is 17 ($0011), the Picture is Vers. 2. 

Just as a Version 1 Picture can have bitmap graphics in it, a 
Version 2 Picture can have a PixMap in it. Any CopyBits calls 
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made following ап OpenPicture, but before a ClosePicture call, 
will store the data into the Picture. If the source was a PixMap 
instead of a BitMap, the Picture handle will have both the bit data 
(compressed format) and a color table (Color Look Up Table or 
CLUT) describing the colors used in the PixMap. 


PICT File Format 

Knowing the Picture format, the PICT File Format is simple. 
A PICT file (ie. one that has the Filetype “РІСТ”) consists of a 
data fork with a 512 byte header followed by a picture data 
structure. The header is usually specific to the application that 
made it (most programs ignore it). After the header, the picture 
data contains picSize, picFrame and then the variable length 
Opcodes. As stated above, do not use picSize to determine how 
much data follows. Instead, check the size of the file with a File 
I/O call. Subtract 512 and that should be the size of the handle 
that the data should be read into. 


Colorimage FKEY Code 

The Colorlmage FKEY was designed to save the current 
screen to file, similar to the Screen Save FKEY (Command- 
Shift-3). Instead of a MacPaint file being created, a PICT file is 
created instead. A CopyBits call on the current screen is used 
when creating the picture handle, which is then saved to the file. 

The FKEY will work on any Macintosh. If the Macintosh 
has Color Quickdraw (ie. Macintosh //), the Color Window 
Manager GrafPort is temporarily set before creating the picture 
handle. Thus a version 2 PICT file will be created and any color 
images on the screen will be saved. On a non-Color Quickdraw 
Macintosh (ie. Mac SE and before), the normal Window Man- 
ager Port is used and a version 1 PICT file is created. If the Caps 
Lock key is pressed, the entire screen is saved to a file. If the Caps 
Lock key is not pressed and a front window exists, only the 
current window is saved to a file. The picture is not saved to a set 
file name like the Screen Save FKEY, instead the user is 
prompted for the file name. The image is also not rotated on a Mac 
П monitor. Thus you won'tneed to edit your screen dumps before 
using them in your documentation, nor will you need to turn off 
your color interface as is the case with the old style shift-cmd-3. 

Remember, if the Screen was a PixMap instead of a Bitmap, 
the CLUT will be saved into the PICT file along with the 
compressed bit data. Color PICTs are amazingly packed files. 


Palette Manager 

Reading a PICT file, however, is only half the job of 
displaying a color image correctly. If the Picture contained Color 
Quickdraw commands (for example, a Color Window saved with 
ColorImage FKEY), the user will want to see the Picture drawn 
again using the original colors. For this, the Palette Manager 
needs to be used. 

The Palette Manager establishes the color environment of 
the Мас//. Itusesthe Color Manager (which controls what colors 
are used) to select the best colors for a given display. The idea is 
that each window can have a Color Palette associated with it. 
These are the Colors that the window wants the screen to be 
showing, in order to view the window at it's best. Unless there 
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are to many windows needing to many colors, each window gets 
it's Palette. If there are not enough colors, highest priority goes 
to the top most window. Every time the top most window 
changes (and it has an associated Palette), the colors may change 
to give the new window it's best appearance. The Palette 
Manager will then issue an update event for all Palette windows 
so that they can be redrawn to their best appearance in the new 
colors. 

While an Application could use the Color Manager directly 
and bypass the Palette Manager, this is not recommended. Such 
programming would fall apart in a color Multiple task environ- 
ment. Remember, Multifinder is not the only such environment. 
There are also color DAs like ColorImage. 

Thus the DA takes the Picture (if itis Version 2), searches for 
a CLUT, and tries to create a Color Palette from it. The program 
does all this by temporarily replacing the low-level quickdraw 
procs (specifically StdBits) with one that checks for a PixMap, 
then transfers the RGB colors into a temporary buffer. The low- 
level routines are replaced and the buffer is converted to a Color 
Palette. Then the Palette is attached to the window so every time 
that particular window becomes the top most, the screen colors 
are set to the Palette. This also causes an update of the window 
So the Picture can be shown in it's best colors. 


Соіоптаде DA Code 

The ColorImage Desk Accessory contains the complement- 
ing code to Color FKEY, and more. The DA creates a window 
(Color Window if the CPU has Color Quickdraw) to display 
Pictures in. The user can then select a PICT file and have it read 
into a Picture handle. Since a user may want to know what colors 
are being used for a specific Picture, the DA allows the users to 
switch between looking at the Picture or the current Palette. 

Think of two ColorImage DA’s that are loaded into the 
system. Each opens a Picture with a radically different CLUT 
(one is a 256 color RGB Picture while the other is a 256 shade 
Gray Scaled one). When the RGB Picture is clicked on, it 
becomes the front window. The Palette Manager sets the 256 
RGB colors (assuming the Color Video Card has 8 Bits per 
Pixel). Both pictures are completely redrawn using the current 
screen colors. Notice the Palette Manager caused the update; the 
program does not have to keep track. The RGB Picture appears 
perfect, while the Gray Picture (which can be seen behind the 
front window) appears as best as it can using the current screen 
colors. Then the user wants to look at the Gray Picture. He clicks 
on that window. It becomes front window, and the Palette 
Manager sets the current screen to 256 shades of gray. The 
windows are redrawn. The Gray Picture appears perfectly, while 
the RGB one appears as best it can using these new gray tones. 


Last Comments 
The ColorImage FKEY and Desk Accessory were created 
with LightS peed Pascal (LSP). Macintosh Programming Work- 
shop (MPW) has it's points. It is an extremely powerful devel- 
opment system perfect for large projects. Being from Apple, 
MPW is the first development system that has any new Trap 
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Listings or new code interfaces. LSP only recently has released 
the Mac // libraries and interfaces. MPW is also the best Object 
Pascal system around. However LSP may be the best environ- 
ment to develop code segments (ie. DA, FKEYs, Window or 
Control Panel Definition Procedures) for the Macintosh. Both 
code examples were tested from inside a test program (a simple 
program that called the FKEY and a modified version of LSP 
DAShell). This decreases development time since the various 
codes could be tested without having to insert the DA or ЕКЕҮ 
into the System file. The code could even be stepped through one 
line at a time, perhaps the best feature of LSP! 

This program requires the Palette manager. When LS Pascal 
version 1.11 was released in September, Think did not include 
the Palette manager, nor the MultiFinder routines. We are still 
waiting for both Think and Borland to upgrade their products to 
MPW version 2.0 interfaces. Y ou can add the Palette manager by 
taking the MPW 2.0 interface and adding it to your project. 
Remove the USES MemTypes and replace with USES Col- 
orQuickdraw instead. Then add "Implementation" to the end of 
the file and your in business. 

ColorImage DA could be expanded to check not only the 
PixMap's CLUT in a Picture, but could check other Color 
Quickdraw commands. Since the DA was designed to work with 
the FKEY, checking the CLUT is all that is needed to function. 
The program could also check for colors that are in the CLUT, but 
are NOT present in the PixMap. Such colors are not displayed 
and need not be in the Palette. 

Yet to come... a full blown explanation of the Palette 
Manager and Palette Animation! 


( ColorImage DA / FKEY by Steve Sheets 12/87 } 

( Saves the current Screen to a PICT file. If Cap Lock ) 
(is down, saves the entire screen. If the key is not & a) 
( Window exists, saves the window.) 


UNIT UColorImageFKEY; 

INTERFACE 
PROCEDURE main; 

IMPLEMENTATION 


( Returns the Color Window Manager Port. ) 
PROCEDURE CGetWMgrPort (VAR CWPort : GrafPtr); 
INLINE 

$АА48; 


( Does this CPU have color Quickdrew? } 
FUNCTION ColorQDExists : boolean; 
CONST 
ROMB5Loc = $28E; 
TwoHighMask = %С000; 


ТҮРЕ 
WordPtr = ^INTEGER; 
VAR 
Wd : WordPtr; 
BEGIN 


Wd := POINTERCROM85Loc); 
ColorQDExists := (BitAnd(Wd^, TwoHighMask) = 0); 
END; 


( Is Cap Lock key down? } 
FUNCTION CapLockDown : BOOLEAN; 
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VAR 
theMap : KeyMap; 
BEGIN 
GetKeys( theMap ); 
CapLockDown := BitTstC@theMap[1], 30); 
END; 


( Given а flag saying color Quickdraw exists, returns) 
(the Handle of а Picture and a flag saying if the window } 
(was saved or if the entire screen was. 
PROCEDURE GetPic (VAR thePic : PicHandle; 
VAR IsWindow : BOOLEAN; 
QDExists : BOOLEAN); 


TYPE 
BitMapPtr = ^BitMap; 
BitMapHd] = “BitMapPtr; 
VAR 


sorcRect, destRect, mapRect : Rect; 
OldPort, WPort : GrafPtr; 

clip, vis : RgnHendle; 

FWin : WindowPtr; 

PixH : BitMapHd1; 

tempMap : BitMap; 


EGIN 
GetPortCOldPort); 


( If Color Quickdraw exists, use the Color Window Manager 
( PixMap. Else use the normal Window Manager BitMap. ) 
IF QDExists THEN 
BEGIN 
CGetWMgrPor tCWPor t); 
PixH := BitMapHdl(WPort^ .portBits.baseAddr); 
mapRect := PixH**.bounds; 


END 
ELSE 
BEGIN 
бе tWMgrPor t CWPor t ); 
Ты := WPort^.portBits.bounds; 


( Chose to save the Window or entire Screen. } 
FWin :- FrontWindow; 
IsWindow := (NOT CapLockDown) AND (FWin © NIL); 
IF IsWindow THEN 
BEGIN 
SetPortCFWin); 
sorcRect := FWin* .portRect; 
LocalToGlobalCsorcRect. topLeft); 
LocalToGlobalCsorcRect .botRight); 
OffSetRect(sorcRect, mapRect.left, mapRect.top); 
END 
ELSE 
sorcRect := mapRect; 
destRect.left := 0; . 
destRect.right := sorcRect.right - sorcRect. left; 
destRect.top :- 0; 
destRect.bottom := sorcRect.bottom - sorcRect.top; 
( Resize the regions so they do not get in the way. ) 
SetPort(WPort); 
vis := WPort^.visRgn; 
clip := WPort^.clipRgn; 
WPort^.visRgn := NewRgn; 
WPort^.clipRgn :- NewRgn; 
SetRectRgn(WPort^.visRgn, -30000, -30000, 30000, 30000); 
SetRectRgn(WPort^.clipRgn, -30000, -30000, 30000, 30000); 


( Create Picture, copy map to it and close the Picture. ) 
thePic := OpenPictureCdestRect); 
CopyBitsC(WPort^.portBits, WPort^.portBits, sorcRect, 

destRect, srcCopy, NIL); 
ClosePicture; 


( Reset the Regions and Рогі.) 
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END; 


DisposeRgn(WPort^ .visRgn); 
DisposeRgn(WPort^ .clipRgn); 
WPort^.visRgn := vis; 
WPort^.clipRgn := clip; 


SetPortCOldPort?; 


( Pick а PICT file to save the Picture into (with correct 
title line). ) 
PROCEDURE PickFile (VAR theReply : SFReply; 


END; 


IsWindow : BOOLEAN; 
QDExists : BOOLEAN); 
VAR 
Pt : Point; 
$1, $2 : str255; 


Pt.h := 60; 
IF QDExists THEN 
$1 := ‘Save Color ‘ 
ELSE 
51 := “Save '; 
IF IsWindow THEN 
$2 := “Window PICT: ’ 
ELSE 
S2 := 'Screen РІСТ:”; 
SFPutFileCPt, CONCATCS1, $2), ^’, NIL, theReply); 


( Given а Picture handle and а reference to a file, create а 
PICT file end save the Picture into it. 


PROCEDURE SeveColorlmage (thePic : 


PicHandle; 
theReply : SFReply); 


TYPE 
add Туре = PACKED ARRAY[1.. 128] OF LongInt; 


theErr : OSErr; 

OK : BOOLEAN; 
FileRef : INTEGER; 
BufSize : LongInt; 
Buf : BufType; 
count : integer; 


GIN 
ОК :* FALSE; 


FileRef := 0; 
theErr := FSDeleteCtheReply.fname, theReply.vRefNum); 
IF CtheErr = noErr) OR CtheErr = fnfErr) THEN 
BEGIN 

theErr := CreateCtheReply.fname, theReply.vRefNum, 


‘WORW’, PICT’); 


IF CtheErr = noErr) THEN 
BEGIN 
theErr := FSOpenCtheReply.fname, theReply.vRefNum, 


FileRef); 
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IF CtheErr = noErr) THEN 
BEGIN 
FOR count := 1 TO 128 DO 
Buf [count] := 0; 
BufSize := 512; 
theErr := FSWriteCFileRef, BufSize, @Buf ); 
IF CtheErr = noErr) THEN 
BEGIN 
BufSize := GetHandleSizeCHandle( thePic)); 
HLockCHandle(CtheP 1c22; 
theErr := FSWriteCFileRef, BufSize, PtrCthePic^22; 
HUnLock CHandle(thePic)); 
IF (theErr = noErr) THEN 
BEGIN 
theErr := FSClose(F i leRef 2; 
FileRef := 0; 
IF CtheErr = noErr) THEN 
BEGIN 
theErr := FlushVol(NIL, theReply.vRef Num); 


OK := TRUE; 
END; 
END; 
END; 
END; 
END; 


END; 
IF NOT OK THEN 
SysBeep(60); 
IF (FileRef € 0) THEN 
theErr := FSClose(CFileRef); 
END; 


(Main FKEY routine: Check if this CPU has Color Quickdraw) 
(Cused by 811 routines). Create the Picture Handle and Pick) 
(aFile. If successful, savethe Picture into the file end) 
( kill the picture.) 


PROCEDURE main; 
VAR 


thePic : PicHandle; 
theReply : SFReply; 
IsWindow : BOOLEAN; 
QDExist : BOOLEAN; 
BEGIN 
QDExist := ColorQDExists; 
GetPicCthePic, IsWindow, QDExist); 
PickFileCtheReply, IsWindow, QDExist); 
IF theReply.good THEN 
SaveColorImageCthePic, theReply); 
KillPictureCthePic); 
END; 


( ColorImage DA by Steve Sheets 12/87 ) 


Displays а PICT file. Checks if the PICT hes а Color) 


( PixMap. If so, use the Palette Manager to display the PICT) 
( in the correct colors. 


UNIT xColorImageDA; 
INTERFACE 


USES 
ColorQuickDraw, PaletteMgr, ColorWindowMgr; 


FUNCTION Main CtheDCE : DCtIPtr; 
IOPB : ParmBlkPtr; 
driveCall : Integer) : OSErr; 


IMPLEMENTATION 


CONST 
DriverOpen = 0 
DriverPrime = 
DriverControl = 2; 
DriverStatus = 3; 
DriverClose s 4; 


; 
1, 


МахРа1 = 512; 
dCtlEnable = 10; 


kNum = 16; 
kBox = 20; 
kHst = 30; 
kVst - 40; 
kVoff = 40; 


kAbout = 

kLoadPic = 3; 
kShowPic = 5; 
kShowPal = 6; 


1; 
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ТҮРЕ 
BufType = RECORD 
Counter : integer; 
CLUTnum : longint; 
B : ARRAYL1..MaxPa1] OF RGBColor; 
END; 
BufPtr = “Buf Type; 
BufHdl = ^BufPtr; 
imageData - RECORD 
imagePic : PicHandle; 
imagePal : PaletteHandle; 
imageID : integer; 
imageWindow : WindowPtr; 
imageMenu : MenuHandle; 
picRect, palRect : Rect; 
ColorFlag, ShowPicFlag : boolean; 
numPal : integer; 
noPicstr, nameStr 
END; 
imagePtr = ^imageData; 
imageHandle - ^imagePtr; 
MyCSpecArray = ARRAYI2..MaxPall OF ColorSpec; 
MyCTabHandle = “MyCTabPtr ; 
MyCTabPtr = “MyColorTable; 
MyColorTable = RECORD 
ctSeed : LONGINT; 
transIndex : INTEGER; 
ctSize : INTEGER; 
ctTable : MyCSpecArray; 
END; 


( Resize the window W to the size R. Updates the entire) 


: Str255; 


( window (window must be the current Grafport). 
PROCEDURE ReSize (W : WindowPtr;R : rect); 
BEGI 

SizeWindow(W, R.right, R.bottom, false); 
InvalRectCR) 
END; 


( Low level Quickdraw Proc. Instead of drawing а) (Bitmap/ 
Pixmap, grabs the Color Lookup Table, end passes) 
(the RGB colors into the buffer (stored in the Window) 
(Ref Con). ) 
PROCEDURE BitInfo (VAR srcBits : PixMap; 
VAR srcRect, dstRect : Rect; 
mode : integer; 
maskRgn : RgnHandle); 
VAR 
tempW : WindowPtr; 
theBuf : BufHdl; 
tempC : MyCTabHandle; 
n, count : integer; 
BEGIN 
GetPor tCtempw ); 
theBuf := POINTERCGetWRef ConCtempW22; 
( Make sure it is a PixMap. 
IF (srcBits.rowBytes < 0) THEN 
BEGIN 
tempC := POINTERCsrcBits.pmTable); 
( Make sure this is a new CLUT. 
IF CtempC^^.ctSeed €» theBuf**.CLUTnum) THEN 
BEGIN 


( Cycle through all colors, stuffing into Ви.) 
theBuf**.CLUTnum := tempC^^.ctSeed; 
n := theBuf**.Counter; 
IF tempC**.ctSize >= 0 THEN 
FOR count := Ø TO tempC^^.ctSize DO 
BEGIN 
IF п < MaxPal THEN 
BEGIN 
п :=п +], 
theBuf^^.B(n] := tempC^^.ctTeble[count].rgb; 


9 


END; 
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theBuf** .Counter := п; 
END; 
END; 
END; 


( Given а window and а Picture Handle, return а) 
( Palette Handle and Palette number of the colors used) 
( in the Picture Handle. 
FUNCTION GetPal CtheW : WindowPtr; 
thePic : PicHandle; 
VAR thePal : PaletteHandle; 
VAR theNum : integer) : boolean; 
TYPE 
myPicHdl = “myPicPtr; 
myPicPtr = “myPicData; 
myPicData = RECORD 
Р : Picture; 
ID : integer; 
END; 
VAR 
count : integer; 
theBuf : BufHdl; 


tempPtr : myPicHdl; 
tempProc : CQDProcs; 
oldProc : QDProcsPtr; 


oldRef : longint; 
dummy : boolean; 
tempP : GrafPtr; 
BEGIN 
dummy := false; 
{ If this is a Handle, ) 
IF thePic © NIL THEN 
BEGIN 
( And if it is а color Picture. ) 
tempPtr := POINTERCtheP ic); 
IF tenpPtr^^.ID = $0011 THEN 
BEGIN 
( Create the Buffer. ) 
theBuf := POINTERCNewHandle(CSizeOf (Buf Type))); 
IF CtheBuf © NIL) THEN 
BEGIN 
( Clear Buffers counters. } 
theBuf ^^ .Counter := 0; 
theBuf ^^ .CLUTnum := -1; 
( Save the old Window RefCon, and stuff Buffer into RefCon.) 
oldRef := GetWRefConCtheW); 
SetWRef ConCtheW, ord4CtheBuf >); 
( Seve the old low level QD Procs, create new ones (including 
BitInfo). ) 
oldProc := POINTERCtheW^ .grefProcs?; 
SetStdCProcs( tempProc); 
tempProc.bitsProc := @BitInfo; 
theW*.grafProcs := @tempProc; 
( Draw the Picture Cgrabing the CLUT and RGB Colors). } 
GetPor tC tempP ); 
SetPort (thew); 
DrewPictureCthePic, thePic^^.picFrame); 
SetPortCtempP); 
theW^.grefProcs := POINTERColdProc); 
SetWRef ConCtheW, oldRef); 
( If there were апу colors, create а Color Palette.) 
IF theBuf**.Counter > 0 THEN 


BEGIN 
thePal := NewPaletteCtheBuf^^.Counter, NIL, pmTolerant, 0); 
IF thePal ‹ NIL THEN 
BEGIN 
dummy := true; 
theNum := theBuf ^^ .Counter; 
FOR count := 1 ТО theNum 00 
SetEntryColorCthePal, count - 1, theBuf^^.B(count 1); 


END 
ELSE 
thePal := NIL; 
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DisposHendleCPOINTERCtheBuf 22; 


END; 
END; 
END; 
GetPal := dummy; 


END; 


( Given references to а PICT file, read the PICT f ile into а 
PICT handle. 
FUNCTION GetPic CtheReply : SFReply; 
VAR thePic : PicHandle) : BOOLEAN; 
VAR 


OK : BOOLEAN; 
FileRef : INTEGER; 
BufSize : LongInt; 
theE : OSerr; 
tempPic : PicHendle; 


BEGIN 
ОК := FALSE; 
FileRef := 0; 


tempPic := NIL; 
theE := FSOpenCtheReply.fname, theReply.vRefNum, 
FileRef); 
IF CtheE = noErr) THEN 
BEGIN 
theE := GetEOF(FileRef, BufSize); 
IF СіһеЕ = noErr) THEN 
BEGIN 
BufSize := BufSize - 512; 
theE := SetFPos(FileRef, fsFromStart, 512); 
IF СіһеЕ = noErr) THEN 
BEGIN 
tempPic := PicHendleCNewHandle(BufSize2); 
theE := MemError; 
IF CtheE = noErr) THEN 
BEGIN 
HLock (Напа 1е( tempPic)); 
theE := FSRead(FileRef, BufSize, POINTERCtempPic* 2); 
HUnLock(Handle(tempPic)); 
OK := (theE = noErr); 
IF OK THEN 
thePic := tempPic; 
END; 
END; 
END; 
END; 
IF (FileRef © Ø) THEN 
FileRef := FSClose(F ileRef); 
IF NOT OK THEN 
BEGIN 
SysBeep( 1); 
IF tempPic © NIL THEN 
DisposHandleCHandle(CtempP ic2); 
END; 


GetPic := OK; 
ЕМО; 


( Load а PICT into the DA. } 
PROCEDURE LoadPic CtheDCE : DCtIPtr2; 
VAR 
theImage : ImageHandle; 
tempReply : SFReply; 


P : point; 
theList : ЅРТуреі ist; 
S : str255; 

BEGIN 


theImage :- ImageHendle(CtheDCE^ .dCtlStorage?); 
WITH theImage^^ DO 
BEGIN 
( Select a File. ) 
Р.В := 60; 
Р.у := 60; 
{һе 15110] := ‘PICT’; 
SFGetFileCP, '^, NIL, 1, theList, NIL, tempReply); 
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IF tempReply.good THEN 
BEGIN 
(If а files is selected, release the old Picture and 
Palette Cif апу).} 
IF imagePic © NIL THEN 
BEGIN 
DisposHandleCHandleCimageP ic2); 
imagePic := NIL; 
picRect.bottom := КВох * kNum; 
picRect.right := kBox * kNum; 
END; 
IF imagePal €» NIL THEN 
BEGIN 
DisposePalette( imagePal ); 
numPal := 0; 
imagePal := NIL; 
( Prepare to set Windows name to ‘ColorImage’ .} 
$ := nemeStr; 
( Read the Picture.) 
IF GetPic(tempReply, imagePic) THEN 
BEGIN 
( If PICT read correctly, resize the window & set the 
Window name to 'ColorImage : (filename)’.} 
picRect.bottom := imagePic**.picFrame.bottom - 
imagePic^^.picFrame.top; 
picRect.right := imagePic^^.picFrame.right - 
imagePic^^ .picFrame.left; 
$ := CONCATCS, ': ', tempReply.fname); 
(If this is Color Quickdraw CPU.) 
IF ColorFlag THEN 
BEGIN 
( Get Palette from Picture.) 
IF GetPalCimageWindow, imagePic, imagePal, 


BEGIN 
( If successful, set the Palette to the Image Window & 
resize the Pal rect.) 
SetPaletteCimageWindow, imagePal, true); 
IF numPal > kNum THEN 
palRect.right := palRect.left + (kNum * 


numpal) THEN 


kBox ) 
ELSE 
palRect.right := numPal * kBox; 
palRect.bottom := (((numPal - 1) DIV kNum) 
+ 1) * kBox; 
END; 
END; 


END; 


( Set the Menu correctly, set so the Picture is displayed 
first, resize the window, and set the Window Title. } 
IF imagePic © NIL THEN 
EnableItemCimageMenu, kShowPic) 
ELSE 
DisablelItemCimageMenu, kShowPic); 
IF imagePal € NIL THEN 
EnableItemCimageMenu, kShowPal) 
ELSE 
DisableItemCimageMenu, kShowPal); 
ShowPicFlag := true; 
ReSizeCimageWindow, picRect); 
SetWTitleCimageWindow, S); 
END; 
END; 
END; 


( Does this CPU have color Quickdraw? ) 
FUNCTION ColorQDExists : boolean; 
CONST 
ROMB5Loc = $28E; 
TwoHighMask = %С000; 
ТҮРЕ 
WordPtr = ^INTEGER; 
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VAR 
Wd : WordPtr; 
BEGIN 
Wd := POINTERCROM85Loc); 
ы ColorQDExists := (BitAnd(Wd^, TwoHighMask) = 0); 
ND; 


Open the DA. Set data structures, Menu, window, etc.) 
FUNCTION Open CtheDCE : ОСИР4г) : OSErr; 
VAR 
tempPort : Grafptr; 
theImage : ImageHandle; 
tmpRect : Rect; 
insideWindow : WindowPeek; 
BEGIN 
getport( tempPort); 
IF theDCE^.dCtlStorege = NIL THEN 
BEGIN 


theDCE^.dCtlStorage := NewHandle(SizeOf( imageData)); 


HLock( theDCE*.dCt Storage); 
theImage := ImageHandle( theDCE* .dCt1Storage); 
WITH theDCE^, theImage^^ DO 

BEGIN 


imageID := dCtlRefNum; 
IF imageID » 0 THEN 

imageID := -imageID; 
imageID :- %000 + 32 * (-1 - imageID); 
imageMenu := GetMenuCimageID); 
IF dCtlRefNum < 0 THEN 

BEGIN 

imageMenu^^.menuID := imageID; 

theDCE^.dctlMenu := imageID; 


END 
LSE 
BEGIN 
imageMenu^^.menuID := -imageID; 
theDCE^ .dctlMenu := -imageID; 
END; 


imagePic := МІ; 

imagePal := NIL; 

numPal := 0; 
DisebleItemCimageMenu, kShowP іс); 
DisableItemCimageMenu, kShowPal); 
picRect.top :- 0; 

picRect.left := 0; 

picRect.bottom := kBox * kNum; 
picRect.right := kBox * kNum; 
palRect := picRect; 

ShowPicFlag := true; 

ColorFlag := ColorQDExists; 
GetIndString(nameStr, imageID, 1); 
GetIndString(nopicStr, imageID, 2); 
tmpRect := picRect; 
OffSetRectCtmpRect, 0, kVoff); 

IF ColorFlag THEN 


END; 


( Do nothing Prime routine. ) 


FUNCTION Prime CtheDCE : DCtlPtr; ІОРВ : ParmBlkPtr) : 


OSErr; 


BEGIN 
Prime := noErr; 
END; 


( Do the Control routine Cie. Events, Menus, е{с.).} 


FUNCTION Control CtheDCE : DCtlPtr; IOPB : PermBIkPtr) : 


05Егг; 


accEvent = 64; 
eccMenu = 67; 


accUndo - 68; 
accCut - 70; 
ассбору = 71; 


eccPeste = 72; 
accClear = 73; 
VAR 
theEvent : EventRecord; 
theImage : ImageHandle; 
aWindow : WindowPtr; 
tempRect : Rect; 
tempPort : Grafptr; 
count : integer; 
BEGIN 
getportCtempPort); 
HLock(theDCE .dCt1Storage); 
theImage :- ImageHandle(theDCE .dCt1Storage); 
WITH theImage** DO 
BEGIN 
SetPor t( imageWindow); 
CASE IOPB^.csCode ОҒ 
accEvent : 
BEGIN 
BlockMoveCIOPB^.ioMisc, @theEvent, 


SizeOf( theEvent)); 


CASE theEvent.what OF 
(Update event: Show the Picture or the Palette.) 
updateEvt : 
BEGIN 
BeginUpdate(WindowPtrCtheEvent .теѕѕаде)); 
SetPort(WindowPtrCtheEvent .message)); 
IF ShowPicFlag THEN 
BEGIN 
EraseRect(picRect); 
IF imagePic <> NIL THEN 
DrawPictureCimagePic, picRect) 
ELSE 
BEGIN 
MoveToCkHst, kVst); 
DrawStr ingCnoPicStr); 
END; 


imageWindow := NewCWindowCNIL, tmpRect, END 


nameStr, true, rDocProc, Pointer(-1), True, 0) ELSE IF ColorFlag THEN 
BEGIN 
imageWindow := NewWindow(NIL, tmpRect, EraseRect(palRect); 


nameStr, true, rDocProc, Pointer(-1), True, 0); 


SetPort( imageW indow); 

insideWindow := WindowPeek( imageWindow); 
insideWindow* .windowKind := dCtlRefNum; 
dCtlWindow := PtrCimageWindow); 


END; 
HUnLock(theDCE~ .dCt Storage); 


SelectW indowCWindowPtr(theDCE~ .dCt1Window2); 
SetPor tCWindowPtr( theDCE*.dCt1Window)); 
END; 
Se tPort( tempPort); 
Open := noErr; 
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IF imagePal © NIL THEN 
FOR count := 0 TO NumPal - 1 DO 
BEGIN 
PmForeColor(count); 
tempRect.top := Ccount DIV kNum) * kBox; 
tempRect. left := (count MOD kNum) * kBox; 
tempRect.bottom := tempRect.top + kBox; 
tempRect.right := tempRect. left + kBox; 
PaintRect(tempRect); 


END; 
END; 
EndUpdate(wWindowP tr( theEvent.message)); 


END; 
( Activate Event: Add or remove the Menu. } 
activateEvt : 


IF BitANDCtheEvent.modifiers, activeFlag) О 0 THEN 
BEGIN 
IF Ord(theEvent.message) = OrdCimageWindow) THEN 
BEGIN 


InsertMenuC imageMenu, 0); 


DrewMenuBar ; 
END; 
END 
ELSE IF OrdCtheEvent .message) = OrdCimageWindow) 
THEN (De-activate event) 
BEGIN 
DeleteMenuCimageMenu* ^ .menuID?; 
DrawMenuBar ; 
END; 
( Mouse Down: Drag the window. ) 
mouseDown : 


IF FindWindowCtheEvent.where, awindow) IN 
[inSysWindow, inContent] THEN 
BEGIN 


SetRectCtempRect, -30000, -30000, 30000, 30000); 
DregWindowCawindow, theEvent.where, tempRect); 
END; 

keyDown, eutoKey : 
ЗузВеер( 1); 

OTHERWISE 

END; 


END; 
( Menus: Do the About Alert, Load a Picture or switch 
between the Picture or Palette. 
eccMenu : 
CASE IOPB^.CSPaerem[ 1] OF 
kAbout : 
count := AlertCimageID, NIL); 
kLoadPic : 
LoadP ic( theDCE); 
kShowPic : 
IF NOT ShowPicFlag THEN 
BEGIN 
ShowPicFlag := true; 
ReSizeCimageWindow, picRect); 
END; 
kShowPal : 
IF ShowPicFlag THEN 
BEGIN 
ShowPicFlag := false; 
ReSizeCimageWindow, palRect); 
END; 
OTHERWISE 
END; 
accUndo, accCut, accCopy, accPaste, accClear : 
SysBeep( 1); 
OTHERWISE 
END; 
END; 
HUnLockCHandle( the Image 22; 
SetPertCtenpPort); 
Control := noErr; 
END; 
( Do nothing Status routine. ) 
FUNCTION Status CtheDCE : DCtIPtr;IOPB : ParmBikPtr) : 
05Егг; 
BEGIN 
Status := noErr; 
END; 


( Close Routine: Clear the Menu, Window, Pelette, Picture 
and Data Structure. 
FUNCTION Close CtheDCE : DCtIPtr; IOPB : ParmBlkPtr) : 
05Егг; 
VAR 
theImage : ImageHendle; 


EGIN 
HLockCtheDCE* . dCtlStorage); 
theImage := ImageHandleCtheDCE* .dCt 1Storage ); 


302 


WITH theImage^^ DO 
BEGIN 

Dele teMenu( imageMenu*^*^ . menuID); 

ReleaseResourceCHandle( imageMenu2); 

DrawMenuBar ; 

IF imagePal «» NIL THEN 
DisposePalette( imagePal ); 

IF imagePic O NIL THEN 
DisposHandleCHandle(imageP ic2)2; 

DisposeW indow( imageW indow); 


END; 
HUnLock( theDCE* .dCt 1Storage); 
IF theDCE^.dCtlRefNum < Ø THEN 
HPurgeCHandleCtheDCE* . dCt Dr iver22; 
theDCE* .dCtlWindow := NIL; 
DisposHendle(theDCE* .dCt lS torage?; 
theDCE* .dCtlStorage := NIL; 
Close := поЕгг; 
END; 


( DAs main routine.) 
FUNCTION Main; 
BEGIN 
CASE driveCall OF 
DriverOpen : 
Main := OpenCtheDCE); 
DriverPrime : 
Main := PrimeCtheDCE, ІОРВ); 
DriverControl : 


BEGIN 
BitClrCétheDCE^.dCtlFlags, 15 - dCtlEnable); 
Main := ControlCtheDCE, IOPB); 
BitSetCétheDCE^.dCtlFlags, 15 - dCtlEnable); 
END; 

DriverStatus : 
Main := StatusCtheDCE, IOPB); 

DriverClose : 
Main := CloseCtheDCE, ІОРВ); 

END; 
END; 
END. 


х ColorImageDA.R 
Resource Source File 
by Steve Sheets 12/87 


% % и 


ColorImageDA Rsrc 


Type MENU 

,7 16000 ColorImage 1.1 by Steve Sheets 
Color Image 

About ColorImage... staticText 

c= 49 104 59 296 


Load Picture Designed for MacTutor 12/87 


Show Picture 
Show Palette 


steticText 
80 40 119 360 
DA - Displays a PICT file. If 


Type STR! it contains a Color PixMap, 
А ," 16000 displays it іп the correct Palette. 
Color Image staticText 


No Picture Available 120 40 139 360 


ҒКЕҮ - Saves the current screen 


Type DITL into а PICT file. 
716000 
Туре ALRT 
, - 16000 

button 60 120 260 520 
160 170 180 230 - 16000 
OK 5555 
staticText 2 
20 95 39 305 Jee) 


© The Definitive MacTutor, Vol. 4 


Macintosh II 


Graphics Devices & Chroma 


The Good(?) Old Days 

How many of you Mac programmers out there remember 
how hard it was to master Quickdraw? Come on, raise your 
hands... Now, how many of you still have trouble sometimes? 
(Yes, my hand is up, too!) Remember those long hours spent 
trying to figure out how SetOrigin works, and wondering which 
regions stick to the window and which ones stick to the GrafPort 
coordinates? Wasn't it a bummer trying to remember why 
FrameRgn and FramePoly produce different results? I can see 
you grimacing as you recall the many hours spent wondering 
where your pictures go when you offset them. I, for one, refused 
to knuckle under, and finally managed to get most of it figured 
out. From the abundance of Mac software out there, it looks like 
a lot of other people persevered as well. 


Apple Consults Ted Turner (or Color, Anyone?) 

Just when we had everything under control, along came 
Color Quickdraw! With it came several new concepts to absorb. 
The most obvious addition to the Mac's graphics system is, of 
course, color. Obvious, that is, to all those lucky enough to have 
acolor monitor attached. People with monochrome screens have 
to settle for lots of shades of gray. Really lucky people can have 
monochrome screens and color screens hooked up at the same 
_ ume! This is where I (very smoothly) slide into a discussion of 
another addition to the Quickdraw system: the ability to have 
several display devices instead of a lone monitor. The phrase 
"display device" could apply to a wide variety of equipment, but 
ГИ limit my discussion to the CRTS we've come to know and 
love. (Foradescription of how the color part of Color Quickdraw 
Works, read Inside Macintosh Vol. 5, and take a look at Steven 
Sheets' article in the September '87 MacTutor). 


Six of One, Half a Dozen of the Other 

As most of you know, the Mac II has expansion slots (for you 
trivia buffs out there, it has six of them). Each of these slots can 
have something really neat plugged into it, like additional proc- 
essors, data acquisition boards, and other stuff like that. But, if 
you don’t have a video card and monitor plugged in, you won’t 
be able to see what's going on. I ought to know. My monitor took 
about a month longer to arrive than my CPU did. The Mac made 
а nice sound when I turned it on, but that got really boring after 
the first couple of hundred times. Anyway, with six slots 
available, enterprising (and loaded) people can plug in six video 
cards to use with many monitors of various shapes and sizes 
(some cards allow more than one monitor to be attached). 

So, with lots of screens putting quite a load on your table (not 
to mention your budget), what would you expect to see? Several 
identical copies of your desktop? Sounds interesting, but not 
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very practical. Quickdraw treats all the video devices collec- 
tively as a single, possibly irregular, display. Windows may be 
placed anywhere on the desktop, and as a result a single window 
can extend across several monitors. The effect is especially 
impressive when adjacent monitors have different color environ- 
ments, or one is color and the other b/w. This spectacular feat is 
accomplished through careful management of graphics devices. 

Graphics Devices can be (loosely) described as anything 
Color Quickdraw can draw into (I'll refer to Color QuickDraw as 
CQD from here on out). By the way, when I mention a graphics 
device I’m not talking about the piece of expensive hardware 
sitting on your desk. I’m referring to the data structure СОР uses 
to describe the piece of expensive hardware. A GDevice record 
holds information about the device's postition in Quickdraw 
space, the color capabilities, color matching routines, and cursor 
handling on the device. Physical devices also have drivers 
associated with them, identified by the gdRefNum field, to 
handle things like changing the depth or color environment. For 
multiple screens, CQD maintains a linked list of GDevices 
(actually, it'salistof handles to GDevices), one for each monitor. 
The head of the list is in alow memory global called DeviceList. 
The screen with the menu bar is described by the GDevice in 
MainDevice, also in low memory. When drawing is happening 
on a device, a handle to it is stored in theGDevice. 

Normally, applications should ignore the fact that their 
windows might extend over more than one screen and let Quick- 
draw take care of the details. Asa matter of fact, programs should 
never (well, almost never) depend on any particular device 
configuration, such as the number of colors present. The user can 
change the environment any time he wants to, one way being 
through the Control Panel. 

Sometimes, though, taking advantage of the way graphics 
devices work can be useful. I’ve written a desk accessory to help 
illustrate some points to keep in mind when dealing with graphics 
devices. I'm not going to go over everything you should know 
about graphics devices here, since Inside Macintosh, Vol. 5 
covers them very well. 


What a Great Name For a Color DA! 

Chroma is a desk accessory that displays all the colors (or 
gray shades) currently available on attached graphics devices. It 
pays attention to the depth (bits per pixel) of each device when 
deciding how many colors to draw. Other useful data are also 
displayed, such as the slot number a device is plugged into, the 
refNum of the driver, the GDevice flags, and the device's mode. 
The flags indicate the presence of several conditions, including 
whether or not the device is the main screen, was initialized from 
RAM, was initialized from a ‘scrn’ resource, is the active screen, 
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has a driver, and is color or b/w. Тһе mode is the number passed 
to the driver, if there is one, to set the pixel depth, etc. 

When the Chroma window lays across more than one device, 
the piece of the window on a device reflects that device's 
environment. That is, a color monitor with 256 colors and a b/w 
monitor with 16 gray shades would cause Chroma to draw part 
of the window with lots of little color squares and the other part 
of the window with big gray ones. The rest of the information 
provided is also pertinent to the device on which it is drawn. By 
positioning the slot number on the boundary between screens, 
you'll see part of a different number on each screen. Chroma 
starts with a rather small window, so you can leave it around to 
examine your color environment and not cover up other areas of 
interest. It supports zooming, though, so you can get a better look 
at the colors of a device. Chroma's window zooms to fill the 
screen where the zoom box was when you hit it. (To learn about 
DA programming in general, see some past issues of MacTutor 
[Ed, how about suggesting some articles here?]). 


A Self-Aware(!) Machine 

Since Chroma's activities take place in (potentially) color 
environments, it needs a color window. But, color windows can 
only be created in the presence of CQD. So, the first thing 
Chroma does when it's opened is to make sure CQD is present. 
Some programs check this by looking at a low-memory global 
called ROMS5 and seeing if they are on a Mac II. It's true that 
CQD only runs on a Mac II, but that may not always be the case 
(we might see a color MacSE, but then again, that's just a silly 
rumor... right?). A much more portable way to detect CQD is by 
calling SysEnvirons. The SysEnvirons call fills in a record 
describing the computer's configuration. SysEnvirons notes the 
presence of CQD, a floating-point coprocessor, and the system 
version, among other things. For a detailed explanation of 
SysEnvirons, see Apple TechNote #129. 

If Chroma is opened on a machine without CQD, it puts up 
a "regular" window instead of a color window, and draws a 
picture complaining about the lack of color tables to display. 
Notice that the b/w window is not allowed to zoom. It seems 
pretty silly to zoom an error message to fill the screen! Chroma 
keeps a boolean in its storage handle to indicate the presence (or 
absence) of CQD, so the window updating mechanism knows 
whether it can use color drawing commands or not. 


How Things Work 

Now I come to the "guts" of Chroma, its drawing proce- 
dures. Chroma draws the contents of its window whenever it 
receives an update event from the Desk Manager (or from itself, 
as explained later). The procedure to draw the contents is named, 
strangely enough, DrawWindow. It is called once for each 
device the Chroma window intersects. It's easy to check for 
intersections, since part of a GDevice is the rectangle, in global 
coordinates, which describes the device's position in Quickdraw 
space. If the contentregion of the Chroma window intersects any 
part of the device, the clip region for the window is set to the 
intersection and DrawWindow is called. 

DrawWindow uses the Palette Manager (PM) to handle its 
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color selections for the various devices. When the color window 
is created, Chroma makes a palette for it using NewPalette and 
installs it using SetPalette. Before drawing on each device, 
DrawWindow copies the color table from it into the palette using 
CTab2Palette. This call resizes the palette, if necessary, to have 
the same number of entries as the color table. А changed palette 
isn't really useful until it'S activated, so ActivatePalette is 
called. When ActivatePalette is called with the frontmost win- 
dow as a parameter, the PM attempts to provide a color environ- 
ment containing as many colors in the palette as itcan. To do this, 
the PM checks the color tables of each device the window 
intersects. It changes the color tables to achieve a best fit. But, 
Chroma isn't designed to change color environments, just to 
show what's already there. Lucky for us, the PM defines a special 
kind of palette entry that causes no change in the color environ- 
ment. These "explicit" colors can be specified in our palette by 
passing pmExplicit in the srcUsage parameter of CTab2Palette. 
(Personal note about the PM: I thought it would be hard to get into 
the spirit of using the PM, but it's not. Everybody writing color 
programs should use the PM. Using the PM will help to ensure 
compatibility with MultiFinder, a wide variety of graphics de- 
vices, and future system software). 

Chroma decides how big to make its color boxes based on 
two things: the current depth of the device, and the size of the 
window. The depth determines how many boxes there will be (2 
for 1-bit mode, 4 for 2-bit mode, 16 for 4-bit mode, and 256 for 
8-bit mode). Actually, Chroma doesn't really know the depth 
(pixel size) of a GDevice, but goes to the color table of the 
device's pixMap to find out how many colors are available. You 
math majors out there probably noticed that with the exception of 
1-bit mode, the number of colors available at each depth is a 
perfect square. So, a square pattern of square boxes makes the 
most sense for displaying the colors. The Chroma window starts 
out wider than it is tall, and the zooming code maintains this 
relationship (even on skinny monitors like Radius FPD). 
Chroma calculates the box size as the vertical size of the window 
divided by the square root of the number of colors. Once the box 
size is calculated, DrawWindow cycles through the pixel values 
as it draws color boxes, selecting colors using PmForeColor 
with the pixel value as its index parameter. 

The data about the device are drawn in the “wider” part of the 
window on the right side. The strings identifying each piece of 
data are in resources, so ambitious users can change them to 
whatever they want. When the window is created, the strings are 
scanned to find the longest one, and that’s how much wider the 
window is extended. I decided to print the numbers іп hexadeci- 
mal, because that is what you'd see in a debugger window. The 
flags and device mode are best read as binary numbers, but hex 
numbers are shorter and hackeroids (like me) can convert hex to 
binary in their heads. 

Earlier, I mentioned updates coming from the DA itself. 
This is necessary to handle moving the window across devices of 
the same depth. No update event is generated by the system if it 
can getaway with just copying the bits from one place to another. 
This is exactly what happens, as long as no part of the window 
moves to adevice with a different pixel size. Since things like slot 
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numbers and flags need to be drawn correctly, Chroma needs to 
know if the window has moved, so it can correctly update the 
data. The Desk Manager handles moving the window, without 
ever notifying the DA (unless part of the window requires 
updating, in which case an update event is eventually passed 
along). Well, DAs have the option of periodically being given 
time by the system occasionally (by setting the drvrDelay field 
and the needTime flag in the driver header). Chroma wakes up 
every 10th of a second or so and checks to see if the window has 
been moved since the last update event. If it has, Chroma 
invalidates the rectangle containing all the info, thereby generat- 
ing an update event for itself. 


Almost Done 

WhichDevice takes a point, in global coordinates, and 
returns a handle to the GDevice containing that point. This 
function is used to figure out where to zoom the Chroma window. 
ZoomWiindow normally fills the main device (the one with the 
menubar), so special care must be taken to zoom the window 
somewhere else. The stdState field of the WState record attached 
to the window contains the "zoomed" size assumed by the 
window in response to a Zoom Window call with the inZoomOut 
part code. By setting this rectangle, Chroma controls where the 
window will go. 

Speaking of zooming, DA's can't follow the “normal” 
detection process when it comes to the zoom box. Normally, 
applications call FindWindow to see which part of which win- 
dow was hit by a mouseDown event. The inZoomIn and 
inZoomOut part codes are returned if the zoom box is hit. But, 
FindWindow returns inSysWindow for DA windows, no matter 
which part of the window is hit. DA's can't gain anything by 
calling FindWindow, because they already know the click was 
somewhere in a DA window! But, with a small bit of trickery, 
FindWindow can be fooled into thinking the DA window is an 
application window. The windowKind field of the window is set 
to the refNum of the DA when the window is opened. The refnum 
is always negative, and that’s how the window manager knows 
the window belongs to a DA. By temporarily making the 
windowKind positive, FindWindow returns meaningful part 
codes instead of inSysWindow. Once a good partCode is 
returned, the windowKind is made negative again. 

Now for another (sort of) tricky part. Once the window is 
zoomed to fill a monitor, and then moved somewhere else, 
there'sno way to make the window smallagain. Hitting the zoom 
box makes the window fill whatever device it's on. So, whatI did 
was add an escape hatch. Holding the option key when hitting 
the zoom box will shrink the window back to its original size. If 
it’s already small, nothing happens. 

The slot number of a given device is determined by the 
WherelsTheDevice function. It takes the refNum of the driver 
. associated with the GDevice, turns itinto a unit number, looks up 
the device control entry in the unit table, and gets the slot number 
from the DCE. All this assumes the GDevice record belongs to 
aphysical device. If therefNum is zero, indicating no driver, then 
the function returns an impossible slot number. 
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Conclusion 

Don't you hate those wind-ups where authors thank every- 
body they've ever known? Well, I don't. I couldn't have done 
this АП by myself, and I want to make sure the people who helped 
get the credit they deserve. Here they are: First my partner Scott 
T. Boyd, the best spell checker I’ve ever used, for being a good 
sounding board. Next, Chris Derossi, Tech Support Technoid, 
for his good advice and unending patience with my last minute 
phone calls. Darin Adler, for some excellent suggestions and for 
being the best darned Cheese Host I' ve ever had the pleasure to 
meet. Now all the rest: TECHNOSTUD, Art, Howard, Doug, 
John, Thug, Pooter, Spaz, Ronnie, Paul, Ollie, and Bill Casey 
(who's not really dead, but running the secret government). 

Any questions, give me a call or drop me a line. 

The MacHax™ Group 

3420D Sandra St. 

Bryan, TX 77801 

(409)846-4102 

айп: С. Marriott, M/S 27-АО 

AppleLink: 20635 

MCImail: Greg Marriott 

BITNET: max@tamlsr 


( 
File Chroma.p 


This is а DÀ to show the current color assignments of 
all connected displays, without taking up the 
whole screen (unless you want to zoom the window! ). 


By Greg Marriott 


Special thanks to Scott T. Boyd, Chris Derossi, 
& Derin Adler 


Copyright 1988, The MacHex" Group. 
All rights reserved. 


1.0d1 1-23-88 Created DA that puts up а window, and 

plots colors of MainDevice 

1.042 1-24-88 Мәде window wider, added slot number 

of MainDevice 

1-24-88 Вееѓед up error detectionCbut not 
necessarily correction %-) 

1.043 1-25-88 Added brag pictures, b/w pictures 
1-25-88 Call SysEnvirons to detect colorQD 
1-25-88 Added word 'Slot^ above slot number 

1.044 1-26-88 Miscellaneous bug/cosmetic fixes 

1.045 1-28-88 Маде updetes smarter. Now it clips to 

each device and draws with their 
charecteristicsCi.e. depth and color 
teble) 

1-28-88 Added zooming, then fixed zooming 

1-29-88 Revised zooming to fill device of 
interest, instead of main device 

1.001 1-29-88 Revved to beta end selected testers 

1.002 2- 4-88 Scott made zooming work right,allowing 

the use of FindWindow. 

1.063 2- 7-88 Began to use Palette Manager, as Chris 

suggested. 

2- 8-88 Added more slot info to window, 
including gdF lags, gdRefNum, and 
gdMode, 811 hex numbers. 

2- 8-88 Revised zooming, added option 
zoom feature 

yt 2- 9-88 Published! 
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($0*) ( Debugging symbols on ) 
UNIT Chrome; 
| _ INTERFACE 


. . MenTypes, QuickDraw, OSIntf, ToolIntf, PaletteMgr, 


= PeckIntf; 


FUNCTION DRVROpenCct РВ : PermBkPtr ; 
dCt1:DCtlPtr2:0OSErr; 
FUNCTION DRVRControlCct IPB :ParmBlkPtr ; 
dCt1 :OCtIPtr):0SErr; 
FUNCTION ORVRStetusCctPB:ParmBlkPtr; 
dCt1:DCtlPtr2:0OSErr; 
FUNCTION ORVRPrimeCct PB :PermBIkPtr ; 
dCt1:DCtlPtr5:OSErr; 
FUNCTION ORVRCloseCctTPB:ParmBlkPtr ; 
dCt1:DCtlPtr):OSErr; 


IMPLEMENTATION 


bwChromaPicture = 0; 
colorChromaPicture = 1; 
sorryPicture = 2; 


infoStrings = 0; 
firstInfoStr = 1; 
slotStr = 1; 
refNumStr = 2; 
flagsStr = 3; 
modeStr = 4; 
lestInfoStr = 4; 


TYPE 
ChromeStorege = RECORD 
theDev ice : GDHandle; 
ninSize:Point; 
windowPlace:Rect; 
hasColorQD :Booleen; 
END; 
ChromaStoragePtr = *ChromeStorage; 
ChromaStorageHandle = “ChromaStorageP tr ; 


EventPtr = “EventRecord; 


trix = RECORD ( needed for some coercive behavior } 


CASE Boolean of 
TRUE : CdontCare :ARRAY(@.. 10] OF Integer); 
FALSE : CtheEventPtr: EventPtr); 

END; 


WStatePtr = “WStateData; 
WStateHandle = ^WStatePtr; 


FUNCTION RsrcIDCdCt] :DCt Ptr; localID: INTEGER): Integer ; 


BEGIN 
( Calculate resource ID’s based on our refNum } 


RsrcID := СВОВС$С000, CBSLCBNOTCdCt1* .dCt IRefNum),5)))) 


+ localID; 
END; 


FUNCTION DRVROpenCct PB :РагиВ 1КР4г;9С41 :DCtIPtr):0SErr; 


FUNCTION MinWindowSize :Point; 
VAR 
theStr ingL ist : Handle; 
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theStr ing: Str255; 
widest: INTEGER; 
1: INTEGER; 
BEGIN 
( The vertical minimum is predetermined } 
MinWindowSize.v := windowVSize; 
widest := 9; 


( Read all the strings, finding the widest one } 
FOR i := firstInfoStr TO lastInfoStr DO 
BEGIN 
GetIndStringCtheString, RsrcIDCdCtl, infoStrings), 
i» 


1 д 
IF StringWidth(theString) > widest THEN 
widest := StringWidthCtheString); 
END; 


( Add а little margin ) 
widest := widest + 2; 
MinWindowSize.h := windowVSize + widest; 
END; ( FUNCTION MinWindowSize ) 


VAR 
oldPort:GrefPtr; 
wFreme :Rect; 
тун indow : WindowPtr ; 
пуй indowS ize :Point; 
theEnv :SysEnvRec; 
envError :05Егг; 
ePalette:PaletteHandle; 


BEGIN 
( If there's no window yet, put one up... ) 
IF dCtl* .dCtlWindow = NIL THEN 
BEGIN 


( Pick а size for the window, even though we're 
gonna change that before the window 
becomes visible ) 
SetRect(wFrame, Ø, 0, windowVSize, windowVSize); 
OffSetRect(wrrame, 100, 100); 


( Ask SysEnvirons about colorQD. If no, put up 
a “regular” window instead of а color window ) 
envError := SysEnvironsC1, theEnv); 
IF theEnv.hasColorQD THEN 
myWindow := NewCOWindowC(NIL, wFrame, ‘Chroma’, 
FALSE, zoomNoGrow, WindowPtr(-1), 
TRUE, LongInt(0)) 
ELSE 
myWindow := NewWindow(NIL, wFreme, ‘Chroma’, 
FALSE, noGrowDocProc, 
WindowPtr(-1), TRUE, LongInt(2)); 


( If the window was created OK, figure out how big 
the window should be end then fill in some 
important fields ) | 

IF myWindow © NIL THEN 
BEGIN 
( Start by setting the text parameters 
and computing а minimum size for the window } 

SetPort(myW indow); 

TextMode(SrcOr 2; 

TextFont (Geneva); 

TextSize(9); 

TextFaceCEL 12; 

myWindowSize := MinWindowSize; 


( Set the window to the min. size, and show it ) 
SizeWindowCmyWindow, myWindowSize.h, 
myWindowSize.v, FALSE); 
ShowW indow(myW indow); 
SelectWindow(myW indow); 


( This one shows that а DA owns the window } 
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WindowPeek(myWindow)* .WindowKind := 
dCt1^ .dCtlRefNum; 


( And this one lets the desk manager know, too ) 
dCtl^.dCtlWindow := PtrCmyWindow); 


( We’1l keep some info in the storage field ) 
dCtl^.dCtlStorege := NewHandle(Size0f с 
ChromaS torage )); 


{ Note whether we put up а color window or not } 
ChromaS torageHandleCdCt1*.dCtiStorage)**. 
hasColorQD := theEnv.hasColorQD; 


( Store the min. size, based on the longest 
description neme in the string list ) 
ChromaStorageHandle(dCt]* .dCt 1Storage)^^ . 
minSize := myWindowSize; 


IF theEnv.hasColorQD THEN 
BEGIN 
( Get the main device, then note the window’s 
global location ) 


WITH ChromaStorageHandleCdCt]^.dCtlStorage)^^ DO 


BEGIN 
theDevice :- GetMainDevice; 
windowPlace := WindowPeekCdCtl^.dCt Window)". 
contRgn^^ .rgnBBox; 
END; 


(Мәке а new palette, and “install” it ) 
ePelette := NewPalette(256, NIL, pmExplicit, 0); 
SetPalette(myWindow, aPalette, TRUE); 


END; 

END; ( if window was created ok... ) 
END; ( if window doesn't exist... ) 
DRVROpen := МОЕгг; 

END; 


FUNCTION DRVRCloseCctTPB:ParmBlkPtr ; dCt]:DCtIPtr):0SErr; 
BEGIN 


( If there's а window up, get rid of it, 
end let the desk manager know, too ) 
IF dCtl*.dCtlwindow © NIL THEN 
BEGIN 
DisposeWindowC(WindowPtrCdCt1^ .dCtlWindow2); 
dCtl^.dCtlWindow := NIL; 
END; 


( If we created storage, get rid of it ) 
IF dCtl^.dCtlStorage O NIL THEN 
DisposHendleCdCt!^.dCtlStorage); 


DRVRClose := №Егг; 
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FUNCTION DRVRControl(ct1PB :ParmB1kPtr; 
dCt1:DCtlPtr5:OSErr; 


FUNCTION WhereIsTheDev iceC(whatDev ice : GCDHandle 5: 
INTEGER; 


CONST 
UTebleBase - $11c; 
VAR 
devRefNum:Longint; 
unitTablePtr: “Ріг; 
unitTableBase :Ptr; 
theDCEHandle : AuxDCEHand1e; 
theDCEHand1ePtr : ^ AuxDCEHandle; 
BEGIN 
(Тһе refnum of the gdevice we’re interested in ) 
devRefNum := whatDevice^^ .gdRef Num; 


( If it’s zero, return an impossible slot number ) 


O The Definitive MacTutor, Vol. 4 


IF devRefNum = 0 THEN 
BEGIN 

WhereIsTheDevice := 42; 
ExitCwhereIsTheDevice); 
END; 


( Turn it into a unit number } 
devRefNum := BNOTCdevRefNum); 


( Grab the unit table address ) 
unitTablePtr := PointerCUTableBase); 
unitTableBase := unitTablePtr^; 


( Go get the address of the device control entry 
for this unit ) 
theDCEHandlePtr := PointerCOrd4CunitTableBase) 
+ devRefNum * 4); 
theDCEHandle := theDCEHandlePtr^; 


{ Return the slot number of this driver } 
WhereIsTheDevice := theDCEHandle** .dCt1Slot; 
END; ( FUNCTION WhereIsTheDevice ) 


PROCEDURE CenterInWindowCVAR theRect:Rect); 
VAR 


rectSize:Point; 
chromaS ize:Po int; 
BEGIN 
( “Home” the rect first ) 
OffsetRectCtheRect, -theRect.left, -theRect.top); 


( Figure size of rect ) 
WITH theRect DO 
SetPt(rectSize, right, bottom); 


( Figure size of window ) 
WITH GrefPtrCdCt1^ .dCtWindow2^.portRect DO 
SetPtCchromeSize, right - left, bottom - top); 


( Position the rect, centered in the window ) 
OffsetRect(theRect, CchromaSize.h - rectSize.h) 
DIV 2, (chromaSize.v - rectSize.v) 


DIV 25; 
END; ( PROCEDURE CenterInWindow ) 
PROCEDURE DrewWindow; 


PROCEDURE DrawNextString(VAR drawWhere:Point; 
drawWhat :Str255; 
drawHow : Style); 

VAR 

someFontInfo:FontInfo; 
oldFace Style; 
BEGIN 
( Save the text style ) 
oldFace := GrafPtrCdCt1^ .dCtlWindow)^ . txFace; 
( Set the desired text face ) 
TextFaceCdrawHow); 


(Тһе “cursor? will be centered already, so move 
back half the width and drew it. ) 
MoveC-CStringWidthCdrewWhat? DIV 2), 0); 
DrawStr ingCdrewWhat); 


( Move the “cursor” up а line, since 
we're drawing from the bottom of the window 
towerd the top. We're letting the descenders 
overhang, since textmode has been set to 5гс0г 
end won't wipe out the overlap. ) 
GetFontInfoCsomeFont Info); 
drawWhere.v := drewWhere.v - someFontInfo.ascent; 
( Re-center the "cursor^ for the next time ) 
MoveToC drewWhere.h, drawWhere.v ); 


( Restore text face ) 
TextFaceColdFace); 
END; ( PROCEDURE DrawNextString ) 


PROCEDURE NumToHexStr ingCaNumber : INTEGER; 
VAR aString:Str255); 
( Meke & 4 digit hexadecimal number 
from en integer ) 


R 
uns ignedNum : LONGINT; 
i: INTEGER; 
aDigit: INTEGER; 
BEGIN 
( Make an unsigned hex number from the 
signed integer 
IF әМитрег>0 THEN 
unsignedNum := aNumber 
SE 


unsignedNum := aNumber + 65536; 


( Make sure the string has 4 digits (spaces)) 
aString := ‘ e 


{ Fill in the digits, from 139 to изд ) 
FOR i := 4 DOWNTO 1 DO 
BEGIN 
201914 := unsignedNum MOD 16; 
IF aDigit< 10 THEN 
eStringli] := chrCord( ‘8’ )+е0151+) 
ELSE 
aStringli] := chrCord( ‘A’ )taDigit- 10); 
unsignedNum := unsignedNum DIV 16; 


END; ( PROCEDURE NumToHexString } 


VAR 
howManyCo lors: INTEGER; 
pixPerSide: Point; 
pixSize:Point; 
por tSize:Point; 
pixNumber : INTEGER; 
oldIndex:INTEGER; 

i,j: INTEGER; 
slotNumberStr ing:Str255; 
theFontInfo:FontInfo; 
sorryP ict:Hendle; 
sorryRect :Rect; 
ePalette:PaletteHendle; 
cursorPt :Point; 

theStr ing:Str255; 

BEGIN 

IF dCtl^.dCtlWindow € NIL THEN 

BEGIN 
WITH ChromeStoregeHendleCdCtl^.dCtlStorage)^^ DO 
BEGIN 

( Prepare to drew the contents of the window ) 
EreseRectCGrefPtrCdCt1* .dCt1Window2^ .portRect?; 


( On а color Mac with CLUT device, show the 
colors, on other mechines, а warning ) 
IF hesColorQD AND CtheDevice^^ .gdType=clutType) 
THEN 
BEGIN 
( What is the size of our window? ) 
WITH GraefPtrCdCt1^.dCtlWindow2^ .portRect DO 
SetPt(portSize, right - left, 
bottom - top); 


( We need to know how many colors ere in 
the clut of the device of interest ) 
howManuColors := theDevice^^.gdPMep^* 
.pmTable^^.ctSize + 1; 


( Assume а square arrangement of colors, 
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except for 2 color mode. Calculate pixel 
size based on vertical size of window, 
assuming that the window will always 
be wider than it is tell ) 
pixPerSide.v := Round(sqrt(howManuColors)); 
IF howManyColors = 2 THEN 
pixPerSide.h := 2 
ELSE 
pixPerSide.h := pixPerSide.v; 


pixSize.v := portSize.v DIV pixPerSide.v; 
IF howManyColors = 2 THEN 

pixSize.h := pixSize.v DIV 2 
ELSE 

pixSize.h := pixSize.v; 


PenSizeCpixSize.h, pixSize.v); 


( Keep track of the pixel number and use 
it to plot the colors in the palette 
we^1] fill from the device’s CLUT ) 

pixNumber :- 0; 


( Fill the palette with the colors from 
the current device, and activate the 
changes ) 

аРа1е {е := GetPaletteCWindowPtr(dCtl* 
.dCtlWindow22; 
CTab2PaletteCtheDev ice^^.gdPMep*^ ^ .pmTeble, 
ePalette, pnExplicit,0); 
ActivatePaletteCWindowPtrCdCt1* 
.dCt Window)); 


( Plot colored pixels one row at а time, 
‘til they're all used up ) 
FOR i := Ø TO(pixPerSide.v - 1) DO 
FOR j := Ø TOCpixPerSide.h - 1) DO 
BEGIN 
( Set the foreColor, and drew a dot ) 
PmForeColor(pixNumber 2; 
MoveToCj * pixSize.h, i * pixSize.v); 
Line(ð, 0); 


pixNumber := pixNumber + 1; 
END; ( Plotting loop... ) 


( Put up some device info, first figuring 
some window positions to put the text, 
starting at the bottom of the window end 
centered in the blank part of the 
window ) 

SetPtCcursorPt, portSize.v + (portSize.h - 
portSize.v) DIV 2, portSize.v - 2 ); 
MoveToC cursorPt.h, cursorPt.v 2; 


( Put up the mode, then its rsrc string ) 
NumToHexStr ingl theDevice** .gdMode, 
theString); 
DrawNextString(cursorPt, theString, [bold]); 
GetIndString(theString, RsrcIDCdCtl, 
infoStrings), modeStr ); 
DrawNextString(cursorPt, theString, 11); 


( Put up flags, then their rsrc string } 
NumToHexStr ingCtheDevice* ^ .gdFlags, 
theString); 
DrawNextString(cursorPt, theString, (6014210; 
GetIndString(theString, RsrcIDCdCtl, 
infoStrings), flagsStr); 
DrawNextString(cursorPt, theString, (1); 


( Put up refNum, then its rsrc string ) 


NumToHexStr ingCtheDevice* * .gdRef Num, 
theString); 
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DrewNextStringCcursorPt, theString, (60191); 

GetIndStringCtheString, RsrcIDCdCtl, 
infoStrings), refNumStr); 

DrawNextString(cursorPt, theString, [1); 


{ Put up the 51048, then its rsrc string ) 
NumToHexS tr ing(WhereIsTheDeviceCtheDevice) - 
8, theString); 
DrawNextString(cursorPt, theString, [bold]); 

GetIndStringCtheString, RsrcIDCdCt1, 
infoStrings), slotStr); 
DrewNextStringCcursorPt, theString, []); 


END ( if on а mac II... ) 
LSE 


BEGIN 
( For non-color Macs, or non-clut devices, 
show а picture saying why Chroma isn’t 
showing pretty colors... } 
sorryPict := GetResource( ‘PICT’, 
RsrcIDCdCtl, sorryPicture)); 


IF sorryPict ‹› NIL THEN 
BEGIN 
( Center the picture in the window, 
and draw it } 
sorryRect := PicHandleCsorryPict)** 
.picFrame; 
CenterInWindowCsorryRect); 


DrawP ictureCP icHandleCsorrgP ict), 
sorryRect); 
Re leaseResource(sorryP ict); 
END; ( if picHendle is good... ) 
END; ( non-color/non-clut condition ) 


( Put up the version number in the 
top right corner) 

GetFontInfoCtheFont Info); 

MoveToCGrafPtrCdCt1* .dCtWindow)^ .portRect. 
right - StringWidthCversID), theFontInfo. 
ascent); 

DrawStr ing(versID); 

END; ( WITH ChromaStorage... ) 
END; ( if window exists... ) 
END; ( PROCEDURE DrawWindow ) 


FUNCTION WhichDeviceCePoint :Point):GDHandle; 
VAR 


aDevice:GDHandle; 
Гоипд0пе :Boolean; 
BEGIN 
( Get first one, and set the initial condition ) 
eDevice :- GetDeviceList; 
foundOne := FALSE; 


WHILE CaDevice <>» NIL) AND NOT foundOne DO 
( essuming it has to be in one of the devices... ) 
IN 


( Check to see if this is the one... ) 
IF PtInRectCePoint, aDevice**.gdRect) THEN 
BEGIN 

WhichDevice := aDevice; 

foundOne := TRUE; 

END; 
{ Get the next device in the list } 
eDevice := aDevice**.gdNextGD; 


END; 
END; ( FUNCTION WhichDevice ) 


FUNCTION EqualRectSize(rect1, rect2:Rect):Boolean; 
( This function is dedicated to Scott T. Boyd %-)) 
BEGIN 
EqualRectSize :=((rectl.right - rectl.left) = 
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(rect2.right - rect2. lef t2) AND 

(Crecti.bottom - recti.top) = 

(rect2.bottom - rect2.top)); 
END; ( FUNCTION EqualRectSize ) 


PROCEDURE ZoomIt(partCode: INTEGER; clickedWhere:Point; 
optKeyDown:Boolean); 
CONST 


mBarHeight = $BAA; 
VAR 


oldRect, newRect:Rect; 
maxHeight : INTEGER; 
menuBarHe ight : ^ INTEGER; 
doZoom : Boolean; 
BEGIN 
( Assume we'll zoom ) 
doZoom := TRUE; 
( Get the old window size, described by the 
content region ) 
oldRect := WindowPeekCdCt1^ .dCtIWindow2^. 
contRgn** .rgnBBox; 


( If the optionKey is down, shrink the window to 
original size... unless, of course, it's already 
original size. ) 

IF optKeyDown THEN BEGIN 
newRect := oldRect; 
newRect.left := newRect.right - 
ChromaStorageHandleCdCt!^. 
dCtlStorage)^^ .minSize.h; 

newRect.bottom := newRect.top + 

ChromaStorageHandleCdCt!^. 
dCtlStorage)^^ .minSize.v; 


( If it’s not already small, make it small, 
otherwise DON’T ZOOM THE WINDOW! } 
IF NOT EqualRect(oldRect,newRect) THEN 
WITH WindowPeekCaCt1^.dCtlWindow)^ DO 
wSteteHendleCdataHandle)^^.stdState := newRect 
SE 


doZoom := FALSE; 
END 
ELSE BEGIN 
( Figure out which device the zoom box was оп, 
50 we know which monitor to fill up with 
the window. } 
newRect := WhichDeviceCclickedWhere)^^ .gdRect; 
InsetRect(newRect, 3, 3); 
newRect.top := newRect.top + 18;( titlebar ) 
( If it’s the main device, make room for 
menu bar ) 
IF WhichDevice(cl ickedWhere )=GetMainDevice THEN 
BEGIN 
menuBarHeight := Pointer( mBarHeight ); 
newRect.top := newRect.top + menuBarHeight^; 
END; 


( Мәке sure that the window will be wider than 
it is tall. It should be no taller than its 
width minus the slot info area on the right 
Side. The info erea's size can be calculated 
from the minSize width - minSize height. } 

WITH ChromaStorageHandleCdCtl^ .dCtlStorage)^^ DO 
maxHeight := newRect.right - newRect.left - 
(ninSize.h - minSize.v); 
( If it's higher than it should be, shorten it ) 
IF newRect.bottom - newRect.top > maxHeight THEN 
newRect.bottom := newRect.top + maxHeight; 


( If we're not already а big window, zoom to it, 
by putting the new size in stdState. 
Otherwise, leave the old size there 
(from lest time)) 

IF NOT EqualRectColdRect, newRect) THEN 
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WITH WindowPeekCdCt1^ .dCtlWindow)^ DO 
wStateHandleCdataHandle)^^.stdState := 
newRect; 
END; ( if not optionkey... ) 


IF doZoom THEN 

BEGIN | 
EraseRect(GrafPtr(dCt1*.dCtlWindow)* .portRect); 
ZoomWindow(WindowPtrCdCt1^ .dCtIWindow), partCode, 


false); 
InvalRectCGrafPtrCdCt1^ . dCtWindow2^ .portRect); 


( Fool ZoomWindow into always zooming “out” by 
changing the "zoomed^ window size ) 
WITH WindowPeekCdCt1^.dCtlWindow?^ 00 

wStateHandleCdataHandle)**.stdState := oldRect; 


END; 
END; ( PROCEDURE ZoomIt ) 
PROCEDURE BragALittle; 
VAR 


aboutPict:Handle; 

aboutRect:Rect; 
BEGIN 
WITH ChromaStorageHandleCdCtl^.dCtlStorage?^^ DO 
BEGIN 
EraseRect(GrafPtr(dCt1*.dCtIWindow)* .portRect?; 


( If they're not on а color Mac, or there's less 
than 16 colors, put up the monochrome version 
of the brag picture. BTW, the boolean short- 
circuits on non-color Macs so Chroma won't 
try to access non-existent data structures ) 

IF «NOT hasColorQD) | 
(theDevice^^ .gdPMap^^.pmTeble^^.ctSize + 1 < 
16) 
THEN 

aboutPict := GetResource( ‘PICT’, 

RsrcIDCdCtl, bwChromaPicture )) 


ELSE 
aboutPict := GetResource( ‘PICT’, 
RsrcIDCdCtl, 
colorChromaP icture)); 
IF aboutPict € NIL THEN 
BEGIN 


( Center the picture, and draw it } 
eboutRect := PicHandleCaboutPict)**.picFrame; 
Center InWindowCaboutRect 2; 


DrawPicture(PicHandleCaboutPict), aboutRect); 
Re leaseResource(aboutPict); 
END; 


( Wait until the button’s not down 
(Hi Roger %-) ) 
REPEAT UNTIL NOT StillDown; 


( Restore the contents of the window ) 
InvaelRectCGrafPtrCdCt1* .dCtlWindow) .portRect 2; 
END; ( WITH... } 
END; ( PROCEDURE BragALittle ) 


VAR 
eventAt: EventPtr; 
oldPort :GrafPtr; 
localPoint :Point; 
aDevice :GDHandle; 
clippyPart :Rect; 
oldClip:RgnHandle; 
thePartCode: INTEGER; 
whichWindow:WindowPtr; 
intersections: INTEGER; 
dumbRect :Rect; 
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BEGIN ( of DRVRContro!l ) 
WITH ChromaStorageHandle(dCt1* .dCtlStorage)^^ DO 
BEGIN 
GetPor tColdPort); 
SetPortCGrafPtrCdCtl^ .dCt lWindow)); 


CASE ct1PB*.csCode ОҒ 
accEvent: 
BEGIN 
( Get the event pointer, through some 
coercive trickery } 
eventAt := trix(ct1PB* .CSParam). theEventPtr; 
WITH eventAt* do 
BEGIN 
CASE what OF 
updateEvt: 
BEGIN 
( Save the current clip region, and 
restore it after the update ) 
oldClip := NewRgn; 
GetClipColdClip); 
BeginUpdeteC(WindowPtrCeventAt*. 
nessage)); 

( If there's no ColorQD, just draw 
the window; otherwise cycle 
through 811 the devices, clipping 
the window to each device ) 

IF NOT hasColorQD THEN 

DrawWindow 

ELSE BEGIN 

aDevice :- GetDeviceL ist; 

( 60 until the end of the list ) 

WHILE aDevice € NIL DO 

BEGIN 

( Check for intersection of the 
content rgn with the device ) 
WITH WindowPeekCdCt1^ .dCtWindow2^ 
DO IF SectRect(contRgn**.rgnBBox, 
eDevice^^.gdRect, 
clippyPert) THEN 
BEGIN 
( Trenslate the global rect 
to local coordinates ) 
GlobalToLocalCclippyPart. 
topLef t2; 
GlobalToLocal(clippyPart. 
botRight); 


( Set the clip, so other parts 
don’t get blasted. 
Set theDevice field of the 
storageHandle to the device 
of interest, then draw } 
ClipRect(cl 1рруРаг{ >; 
theDevice := eDevice; 
DrewWindow; 
END;( if intersect... ) 
( Go to the next device in the 
device list ) 
Әбеуісе := eDevice^^.gdNextGD; 
END; ( while there's more devices...) 
END;( if а color machine... ) 


EndUpdateCWindowPtrCeventAt" . 
message )); 


( Restore the clip, axe the region ) 
SetClipColdClip); 
DisposeRgnColdClip); 


( Mark the window s position ) 
windowPlace := WindowPeekCdCtl^. 
dCt1Window2^ .contRgn^^ .rgnBBox; 
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END; 
mouseDown: 
BEGIN 
localPoint := where; 
GlobalToLocalClocalPoint); 


{ Pretend this isn’t a DA window to 
fool FindWindow ) 
WITH WindowPeekCdCt1^.dCtlWindow)^ DO 


windowKind := -windowKind; 
thePartCode := FindWindow(where, 
WindowPtrCdCt1^. 
dCtlWindow2); 
WITH WindowPeekCdCt1^ .dCtlWindow)^ DO 
windowKind := -windowK ind; 


( In zoom box, do it, passing along 
the state of the option key... ) 
IF CthePartCode=inZoomIn) OR 
CthePar tCode=inZoomOut) THEN 
BEGIN 
IF TrackBoxCWindowP tr(dCt1* 
.dCt Window), where, 
thePartCode) THEN 
ZoomItCthePartCode, where, 
BitAnd(modifiers, 
optionKey) O0); 
END ELSE 
( See if they clicked on the vers. 
number. If so, put up a brag 
picture 'til they release the 
button ) 
WITH localPoint, 
GrafPtrCdCt1^.dCtlWindow?^. 
portRect DO 
IF (h > right-StringWidth(versID)) 
AND Cv « 12) THEN 
BEGIN 
BragAL ittle; 
END;( if h and v in range... ) 
END; ( mouseDown case ) 
END; ( cese what ... } 
END; ( with eventAt... ) 
END; ( accEvent Case ) 


accRun: 
BEGIN ( the periodic call ) 
WITH ChromaStorageHandleCdCtl^. 
dCtlStorage?^^ DO 
BEGIN 


( This is а problem on multiple device 
systems, check for CQD ) 
IF hesColorQD THEN 
BEGIN 
( Moved? If yes, inval the info part 
of the window ) 

IF NOT EqualRect(WindowPeekCdCt1^ . 
dCtlWindow2^. 
contRgn^ ^ .rgnBBox, 
windowPlace) THEN 

BEGIN 

clippyPart :-GrafPtrCdCtl^.dCtlWindow)^. 
portRect; 
clippyPart.left := clippyPart.left + 
clippyPart.bottom; 
InvalRectCclippyPart); 
END; ( if window moved... ) 
END; ( if has color quickdrew... ) 
END; ( with chromestorage... ) 
END; ( accRun cese... ) 
END; ( case ct1PB*.csCode ) 


SetPortColdPort); 
DRVRControl := NoErr; 
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include “Турев.г” 
8include *MPWTypes.r"^ 


type 'DRVR' as 'DRVW'; 


END; ( with dctl^.dctistorage... ) 


END; ( of DRVRControl ) 


FUNCTION DRVRPrimeCctIPB:PermBlkPtr;dCt!:DCtlPtr):0SErr; 
BEGIN 


DRVRPrime := №Егг; 


END; 
FUNCTION DRVRS tatus(ct1PB :ParmBlkPtr ; dCt1:DCt1Ptr2:0SErr; 
BEGIN 


DRVRStatus := NoErr; 


END; 
END. (of Chroma ИМТ} 


Chroma Make File for MPW 
Chroma.DA f Chroma.DRVW Chroma.r 


Rez -rd -c DMOV -t DFIL Chroma.r -o Chroma.DA 


Chroma.DRVW f Chroma.p.o 


Link -w -rt DRVW=0 д 
-sg Chroma à 
* (Libraries) "DRVRRuntime.o à 
Chroma.p.o à 
* (Libraries) "Interface.o д 
* (PLibraries)^Paslib.o д 
-0 Chroma.DRVW -c *????^ -t 17777” 


Chroma.p.o f Chroma.p 


Pascal Chroma.p 


* File Chroma.r 
x 


* Copyright The MacHax™ Group, 1988 
* All rights reserved. 
x 


%7 
/* To get system types */ 
/* To get ‘DRVW’ type */ 


/* Мар 'DRVW^ => 'DRVR' */ 


/* 


* This will produce а DRVR resource from the special 
* DRVW type. 
x 


* Note that the ID 12 is irrelevant, since the 
* Font/DA Mover will renumber it 
* to something else when installing it anyway. 


The leading NUL in the resource name is required to 
conform to the desk accessory naming convention. 


The resource is declared purgeable. If the code were 
to do funky things like SetTrapAddress calls 
(requiring the code to be around at all times), we 
would have to set it nonpurgeeble. 


% 2 w е изии и м 


"define DriverID 12 
resource “ОКУ? (DriverID, “,0х00Сһгота”, purgeable) ( 


/* 
* DRVR flags 
%/ 


dontNeedLock, /* OK to float around */ 
needT ime, /* Periodic Control calls */ 


dontNeedGoodbye, /* No special requirements */ 
noStatusEnable, 

ctlEnable, /* Enable Control calls */ 
noWriteEnable, 

noReadEnable, 


, /* drvrDelay - 1/18 second */ 
updateMask * mDownMask, /* drvrEMask - Event mask */ 


ыт: RR RE 
Chroma Resource File іп REZ Format 


/* 
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0, /* drvrMenu - № menu */ 


“Chroma”, /* drvrName */ 
/* 


* This directive inserts the contents of the 
* DRVW resource produced by linking DRVRRuntime.o 


ж with our DA code 
x 


$$resourceC^Chroma.DRVW^, ‘DRVW’, 0) 


д 


"def ine infoStrings 0 


resource ‘STR®’ ( C 0хС000 | C DriverID << 5 22 + 


infoStrings ) ( 


( 
“Slot”; 
“gdRefNum? ; 
“gdF lags’; 
*gdMode" 


д 


); 


"def ine bwChromaPicture 0 
"define colorChromaPicture 1 
"gef ine sorryPicture 2 


resource ‘PICT’ € C 0х(000 | С DriverID << 5 22 + 


colorChromaPicture ) ( 

2504, 

(13, 137, 96, 265), 

%%0011 02ҒҒ 0С00 FFFF FFFF 0089 0000 0000” 
$^0000 0109 0000 0060 0000 0000 0000 001Е” 
%%0001 000A 0000 0000 015Е 0188 0098 8040" 
$70000 0089 0060 0109 0000 0000 0000 0000" 
$^0048 0000 0048 0000 0000 0004 0001 0004" 
%%0000 0000 0000 ІҒ10 0000 0000 0000 0004" 
$^8000 000F 0000 FFFF FFFF FFFF 0000 ҒС00" 
$^F37D 052Е 0000 FFFF 648A 028C 0000 0068” 
$^08C2 06А2 0000 F2D7 0856 84ЕС 0000 46ЕЗ" 
%%0000 АБЗЕ 0000 0000 0000 0400 0000 0241" 
%”АВ54 EAFF 0000 ІҒ21 8793 1431 0000 0000" 
$^64AF 1180 0000 5600 2290 0524 0000 9007" 
%97160 3A34 0000 (000 С000 COBB 0000 8000" 
%%8000 8000 0000 4000 4000 4000 0000 0000" 
%%0000 0000 0000 0089 0060 0109 0000 0089" 
%%0060 0109 0000 02C1 0002 C100 0201 0008" 
%”Ғ000 0201 1110 0500 @EF7 0000 O3FE 33FE" 
%%0002 1111 1005 000Ғ Ғ800 0003 FD33 0530" 
%%0000 1111 1005 0008 Ғ800 FB33 0300 0111" 
$^1104 0010 F900 0003 FE33 0603 3333 0001" 
$21111 0400 21F9 00ҒЕ 3307 0000 3333 0001" 
$71110 ҒС00 0188 88ҒА 0003 0777 7770 F100" 
$^FE44 0040 FADO 26Ғ9 0008 3333 3000 0333" 
$73300 01Е0 1102 1000 00ҒС 8803 8000 0007" 
$^FD77 0100 00ҒС 66F9 00ҒВ 44ҒВ 0029 ҒА00" 
$"0803 3333 0000 0333 3300 FB11 0100 02ҒВ” 
$78801 0000 ЕСТТ 0170 00ҒС 6600 60FE 66ҒЕ” 
%%0000 O4FB 44ЕВ 0028 ҒА00 0803 3333 0000" 
$^0333 3000 FB11 0210 0008 FC88 0100 OTFC" 
$77701 7000 F866 0260 0000 ҒЕ44 0340 0444" 
$^44FB 002Е ҒА00 0203 3330 FBOO FB11 0810" 
$^0008 8888 8088 8800 ҒЕТТ 0400 0777 1000" 
$^"FE66 0006 ҒВ66 0800 0444 4440 0004 4444" 
ФҒВ00 30FA 0002 0333 30ҒВ 00ҒЕ 1107 1001" 
$71110 0008 8888 FD0O 0877 7770 0007 1110” 
$^0066 6660 00ҒВ 6608 0004 4444 0000 0444" 
$"40FB 0034 ҒА00 0203 3330 ҒВ00 FE11 0710" 
$0111 1000 8888 80ҒЕ 000С 0777 7100 0001" 
$^7776 0066 6660 ØØFE 6608 0066 6600 4444" 
$^4000 0044 4440 ҒВ00 ЗАРА 0002 0333 30ҒВ” 
$"00FE 1107 0001 1110 0088 8880 ҒЕ00 1807" 
$77777 0000 0771 7006 6666 0000 6666 6000" 
$6666 0044 4440 0000 4444 40Ғ8 0032 FADO" 
$^0203 3330 ҒВ00 FE11 0600 0111 1000 8888" 
$^FDOO 1А07 7770 0000 0777 7006 6666 0006" 
$°6666 0000 6666 0044 4400 0004 4444 ҒА00" 
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$°32ЕА 0002 0333 30ҒВ 00ҒЕ 1106 0011 1110" 
%”0088 88FD 001A 0777 7000 0077 7716 0666" 
%”6000 0666 6600 0066 6600 4444 0000 0444" 
$^44ЕА 0032 ҒА00 0203 3333 ҒВ00 0911 1110" 
%%0011 1110 0888 8820 0017 0777 7000 0011" 
$*7770 0666 6000 0666 6000 0066 6600 4444" 
$^0000 FE44 ҒА00 35FA 0012 0333 3300 0003" 
$^3330 0011 1110 0011 1100 0888 8820 0017" 
$"0711 7000 0777 1110 6666 6000 0666 6000" 
%”0666 6600 4444 4004 FE44 FADO 2FF9 00ҒЕ” 
$"330E 0033 3330 0011 1110 0111 1100 0888" 
%%80Ғ0 0003 0777 7707 FETT 0С00 6666 6000" 
$"6666 6000 0666 6600 ҒА44 ҒА00 2CF9 00ҒВ” 
%%3308 3000 1111 0001 1111 0008 8880 Ғ000" 
%%0007 ЕСТТ 0070 0066 6600 0066 6660 0006" 
$^6660 00ҒА 4400 40-8 0020 Ғ900 0003 FC33" 
$"0800 0011 1100 0111 1000 0888 BBFC 00ҒС” 
%”770Е 0000 6666 0000 6666 0000 0666 6000" 
$^04FB 4400 40FB 0033 Ғ800 0003 ЕЕЗЗ 0030" 
%%0000 1111 0001 1110 0008 8880 ҒС00 0007" 
$°ҒЕТТ ҒЕ00 0C66 6600 0066 6600 0006 6660" 
%%0000 ҒЕ44 0300 0444 40FB 0002 C100 0261" 
$°0002 C100 02С1 0002 C100 @BFE 0001 0ҒҒ0" 
$"t400 00ҒҒ E400 20FE 0001 OFFO Ғ700 010Ғ” 
$^FFF1 0004 OFFF 000Ғ FOF4 0000 FFFC 0004" 
$ OFFO 0000 FFFF 0018 ҒЕ00 0ФҒҒ F700 010Ғ” 
$"FFFO 0004 OFFF OFF РОЕЕ 0004 OFFO 0000" 
$"FFFF 003F ҒЕ00 O7FF FFFO ØØFF 000Ғ FOFE^ 
$^0000 FFFE 000A OFFF FFFO ФЕРЕ Ғ000 00ҒҒ” 
$"FOFD 0009 FFFF ØFFF Ғ000 OFFF ҒҒ00 FEFF" 
$°090Е FFFF FOOF Ғ000 OFFF OO0FE ҒҒ04 ОҒҒҒ” 
$^FFFO 003Е ҒЕ00 OBFF FOFF 0ФҒҒ 000Ғ FOOD" 
$"000F FOFE 000A OFFF 0000 ҒҒ00 ҒҒ00 0ҒҒ0" 
$"FFFD 00ҒЕ FF19 ØFFØ ОРЕ OOFF OOFF FOOD" 
$ OFFF 0000 OFFO 00ҒҒ OFFO OOFF 0000 OFFO" 
$“FFOO 40ҒЕ 0006 ҒҒ00 OFFO FFOO FFFE 000Ғ” 
$°0ЕЕ@ OFFF 000Ғ FOOD OFFO OOFF BOFF 00ҒҒ” 
$^FE00 100Ғ FOFF FFOF Ғ00Ғ Ғ000 ҒҒ00 ҒҒ00" 
%”000Ғ Ғ000 000Ғ FOOF FOOF Ғ000 ҒҒ00 000Ғ” 
$"FOFF 0040 ҒЕ00 O6FF 000Ғ FOOF FFFO ҒЕ00" 
%”0ҒОЕ FOFF ØFFØ OFFS 000Ғ FFFF Ғ000 ҒҒ00" 
$"FFFE 0010 OFFO FFFO ҒҒ00 ҒҒ00 ОҒҒ0 00ҒҒ” 
$"0000 OFFO 0000 OFFS ҒҒ00 OFFO 00ҒҒ 0000" 
$’OFFO ҒҒ00 4009 0000 OFFO GOOF FOOF FFFO" 
$°ҒЕ00 OFOF Ғ000 OFFO ҒҒ00 000Ғ FOOD 000Ғ” 
$’FOOF FFFE 000Е OFFO ҒҒ00 ҒҒ00 ҒҒ00 0ҒҒ0" 
%”0ҒҒ0 0000 FFFE 000А ҒҒ00 ҒҒ00 ØFFØ OFFO" 
%%0000 FFFE 003Е 0800 000Ғ Ғ000 ҒҒ00 00ҒҒ” 
$^FCO0 ВЕРЕ OOFF ØØFF 0000 OFFO 0ҒҒ0 OFFO'" 
$"FFFF ҒЕ00 ФЕРЕ 0000 OFFO OOFF 00ҒҒ FOOF" 
%%-000 DOFF ҒЕ00 OAFF OO0FF 0ФҒҒ 000Ғ FOOD" 
%”00ҒҒ ҒЕ00 3E08 0000 OFFF FFFO 0000 ҒҒҒС” 
$^0004 OFFF Ғ000 FFFE 0006 FFFF 0000 FFFF" 
$°ҒОҒЕ 000Е ҒҒ00 000Ғ Ғ000 ОҒҒҒ FFFO 0ҒҒ0" 
%%0000 FFFE 000А FFOO OFFF Ғ000 OFFO 0000" 
$“FFFE 000С ҒА00 010Ғ FOEF 0001 OFFS DEOO" 
$°00ЕА 0001 OFFO Ғ100 020r FOFF 0000 0ВҒА” 
$^0000 FFEF 0001 FFF® 0000 0201 0002 C100" 
%”02С1 0002 C100 02С1 0002 C100 0201 0002" 
$"C100 02C1 0002 C100 0201 0002 C100 02С1" 
%%0002 C100 0703 000Ғ FFFO C500 3215 00Ғ0" 
$°000Е 0000 Ғ000 OFFF 000Ғ FFØ OFFF 0000" 
$“@FFF FFOF FBOO 03Ғ0 0000 ҒОҒС 0002 F000" 
$Р0ЕС 0008 OFFF Ғ000 Ғ000 OOFF FOF? 0031" 
Ф”150Ғ 00ҒҒ 00-0 OFFO 00-0 00-0 FOOD FOFO" 
$"00F0 0000 0Ғ00 OFFB 0003 ҒҒ00 OFFO ҒС00" 
%”02Ғ0 00-0 FBOO 07-0 FFOF Ғ000 ØF OFFI" 
$°003Е 1В0Ғ 0Ғ00 00-0 00Ғ0 00Ғ0 BOFO FOOD" 
$^roro 00-0 0000 OFOO OFFF 000Ғ Ғ000 00Ғ0” 
%”Ғ000 OFFO OOFF 00Ғ0 00-0 OFFO 0Ғ00 OF BO" 
$"FDFO 0000 0Ғ00 000Ғ OFFO OFFS 0Ғ00 ҒОҒҒ” 
$“F041 OFOF 0Ғ00 00-0 00Ғ0 OOF FFFO OFFF” 
%”000Ғ FFFE 002С 0Ғ00 0Ғ00 FOFO 0Ғ00 BOFO" 
$0500 Ғ000 OFOF 00-0 FFFF Ғ000 0Ғ00 РРО" 
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$"00F0 Ғ000 Ғ000 0Ғ00 FFOF Ғ000 FOOF 0Ғ00" 
$"FeFO OF3D 060Ғ OOFF 00-0 00Ғ0 ҒЕ00 21Ғ0" 
$*Ғ000 FOFO 00-0 0000 0Ғ00 0Ғ00 FOFF ҒҒ00" 
%”00Ғ0 0000 FOOF FFOF 0000 Ғ000 FOOF FFQO" 
%”ОҒҒА 000С 0Ғ00 OFOF 0000 FOOF 0Ғ00 FOFQ" 
$^ОЕЗЕ 1800 Ғ000 0-00 00-0 0000 0Ғ00 Ғ000" 
$"FOFO 00-0 0000 0-00 0-00 FOFO ҒЕ00 10Ғ0" 
$"0000 FOFO OFOF 00-0 Ғ000 FOFO 0Ғ00 FOFO" 
$"FBOO OCOF 000Ғ 0-00 00-0 OFOF 00Ғ0 Ғ00Ғ” 
%%300Ғ 000Ғ FFFO 0000 Ғ000 OFFO 000Ғ ҒҒ00" 
$“@FFF ҒЕ00 190Ғ 000Ғ 00-0 OFFO 0000 Ғ000" 
%”00Ғ0 ВЕРЕ @@FF 00Ғ0 00Ғ0 OFFF 0Ғ00 OFFA” 
%”0008 FFFØ 0Ғ00 000Ғ Ғ000 FFFO ЕЕЕ@ 05С3" 
%%0001 Ғ000 05С3 0001 Ғ000 02С1 0002 C100" 
%%02С1 001Ғ Ғ600 10-0 OOFF OFFO 000Ғ FFFQ" 
$"00F0 0000 0-00 000Ғ FCOO OIFF FFEF 0000" 
$^FOF7 001Е Ғ600 08Ғ0 000Ғ 00-0 000Е 000Ғ” 
$"FD0O 030Ғ 0000 OFFC 0002 Ғ000 FOFO 0000" 
$"FOF7 0031 Ғ700 280Ғ 0Ғ00 0Ғ00 Ғ000 0Ғ00" 
%”0ҒОҒ FOOF FFOF FFOO FFFO OFFF 0000 Ғ000" 
$*FOOF Ғ000 FFFO OFFO OFOF ЕФЕ? 00Ғ0 OFFQ" 
$"00FF FOF7 0031 Ғ700 130F 0Ғ00 0Ғ00 Ғ000" 
$ OFFF Ғ000 FOFO OFOF 00Ғ0 0Ғ00 FOFE 0014" 
$^FFFF 00-0 OFOF 0000 FOOF OFFO 000Ғ 0Ғ00" 
$ FOOF 0Ғ00 ҒОҒТ 0031 Ғ700 2BFF FFFO 0Ғ00" 
%%000 OFOF 0000 FOFO OFOF 00Е 0Ғ00 ØFFØ" 
%%0000 FOF® OOFF FFOO ҒҒ00 FFFF 0Ғ00 000Ғ” 
%%0Ғ00 FFFF 0Ғ00 FOF7 0031 Ғ700 1АҒ0 00Ғ0" 
$ OFOD Ғ000 0Ғ00 Ғ000 FOFO OFOF 00Ғ0 0Ғ00" 
$"000F 0000 FOOF 00Ғ0 ҒЕ00 03Ғ0 Ғ000 ФЕРЕ” 
%%0006 Ғ000 Ғ000 0-00 FOFT 0032 Е700 21FQ" 
%”00Ғ0 OFOD Ғ000 0Ғ00 0Ғ00 FOOF FFOF 00Ғ0" 
$"00F0 FFFO 0000 Ғ000 FOOF FOOF FFOO OFFQ' 
$“OFFE 0007 Ғ000 OFFO OOFF FOOF F800 Ø6EA” 
%%0000 0Ғ09 0007 ЕВ00 010Ғ Ғ009 0002 C100" 
$"02C1 0002 C100 02С1 0002 C100 GOFF" 


resource ‘PICT’ € € 0xC000 | C DriverID << 5 
bwChromaPicture ) ( 

1023, 

(83, 167, 166, 295), 

%”1101 A000 8201 000A 0000 0000 0200 0240" 
$"9800 1200 5300 A000 A601 2800 5300 A700" 
%”А601 2700 5300 A700 A601 2700 0002 ЕҒ00" 
$"02EF 0002 EFOO 06ҒС 0000 3CF5 0008 ҒЕ00" 
$"020F Е07С Ғ500 08ҒЕ 0002 3FFO ТСЕБ 0008" 
$"FEO00 027F F8F8 F500 08ҒЕ 0002 FEF8 F8F5" 
$"0011 0900 0001 F878 Ғ001 E000 3FFD 0000" 
$"TFFE 0013 0Е00 0001 FOF8 FFC1 FFCO FF87" 
$ FEO OIFF EOFF 0013 0-00 0003 EOF9 FFE1" 
$“FFE1 FFC7 FFTE O3FF EOFF 0013 0Ғ00 0003" 
$"EOF1 FFFØ ҒҒЕЗ FFC7 FFFF 07F3 E@FF 0013" 
$"0F00 0003 С001 ҒҒҒй FDE7 ЕЗСТ EFFF 8FC3" 
$"EOFF 0013 0-00 0003 (001 FCFO Ғ807 C3C7" 
$^C7FF 8F83 COFF 0013 000 0003 (001 ЕСЕ1" 
$"FO0F 83C7 СТЕТ 9-07 COFF 0013 0Ғ00 0003" 
%%С001 F8F1 FØØF 83СҒ 87C7 9Ғ07 СЕЕ 0013" 
$"0F00 0003 С001 F8F1 EQOF 03СҒ 8Ғ87 9Е0Ғ” 
$^80ЕЕ 0013 0Ғ00 0003 COO! FOF1 EOOF 07СҒ” 
%”0Ғ87 9E@F 80ҒҒ 0013 0Ғ00 0003 Е001 Е1Е3" 
%”Е00Ғ 07СҒ 0Ғ07 9Е1Е 80ҒҒ 0013 0Ғ00 0003" 
$"E0F1 F1E3 EQOF OFOF ØFØF ОҒЗҒ 80FF 0013" 
$"0F00 0001 FOF1 F3E3 COOF ВЕЧЕ IFOF OFFF^ 
$"80FF 0013 0Ғ00 0001 FFF1 ЕЗЕЗ COOF ЕҒ1Е” 
$“1Р70Е OFFF COFF 0012 ҒЕ00 OCFF E1E3 C3CÓ" 
$"07FE 1Е1Е ØFØF FFCO FFOO 12ҒЕ 000С 3FC1" 
%”ЕЗСЗ C003 FB1E 1EOF 07E3 COFF 0002 ЕҒ0 0" 
%”02ЕҒ 0002 ЕҒ00 02ЕҒ 0002 ЕҒ00 0901 0003" 
$"FA00 0018 Ғ900 1305 0003 0000 0380 FEQQ" 
%”0838 C000 0006 0030 6000 1104 0006 0000" 
$"0EFD 0001 3900 FDOO 0230 6000 1311 0007" 
%”С630 180F CF07 0078 СЗЕТ EFCC З9ЕВ Ғ000" 
%”1311 0007 6630 300Е 1980 807Е C667 0Е0С” 
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$^6C60 (000 1311 0006 3660 338C 3199 800Е” 
$^CC66 0С0С СС60 С000 1311 0006 33С0 36CC” 
$^3F19 8000 98C6 0С00 8С60 С000 1311 000С” 
$^33C0 3008 3033 8009 98CC 1819 8CC1 8000" 
$^1311 000С 6180 1998 3337 8183 19CC 1819" 
$^98C1 8000 1311 000Ғ C180 0Ғ18 1Е1Е 0183" 
$"0FCC 1818 FOC1 8000 0402 0000 O3FD 0000" 
$"03F7 000A 0200 0003 Ғ000 0036 Ғ700 0А00" 
$"0000 06Ғ0 0000 1CF7 0002 EFØØ 02ЕҒ 0002" 
%”ЕҒ00 02ЕҒ 0002 EFOO 02ЕҒ 0002 EFOO 02ЕҒ” 
$^0002 ЕҒ00 02ЕҒ 0002 ЕҒ00 02ЕҒ 0002 EFØØ" 
%”02ЕҒ 0005 0100 ЗСҒ1 0012 OEO0 4210 E38E” 
%”0ҒАй 0104 0044 003С 41С0 FEØØ 120Е 0099" 
$^3114 5102 2001 8С00 4400 16C2 20FE 0013" 
$^1100 А111 1451 0238 C154 C644 C895 4208” 
$7325C 0013 1100 A110 F38E 0225 2124 2976” 
$^2514 426C 4452 0013 1100 9910 1451 0225" 
$"E104 E844 E200 0228 4452 0013 1100 42 10" 
$"2451 0225 0105 2945 2500 0228 4452 0013" 
$^1100 3С10 C38E 0224 C104 E644 E880 01С8" 
$^31DC 0005 Ғ100 0110 0005 Ғ100 0110 0002" 
$"EF00 02ЕҒ 0002 ЕҒ00 10FE 0006 046С 3С40" 
$^8200 78FD 0000 40FE 0010 FEJØ 0604 2422" 
$"0082 0044 FDOO 0040 ҒЕ00 11FE 0008 QA24" 
%22СЕ E738 44C7 3201 3160 ҒЕ00 11ЕЕ 0008” 
$"0A24 3C52 9240 7928 4BØA 4440 FE00 1ІҒЕ” 
$^0008 1-24 2852 9230 51E6 7A0A 7A40 FEQQ" 
$" ПРЕ 0008 1124 2452 9208 4001 4204 4240" 
%%ҒЕ00 11FE 0008 1124 224E 9170 44СЕ 3204" 
$^31C8 ҒЕ00 06ҒВ 0000 02Е6 0006 FBOO 000С” 
$"F600 02ЕҒ 0002 ЕҒ00 O2EF 0002 ЕҒ00 Q2EF" 
%”00А0 0083 ҒҒ” 


resource ‘PICT’ С С 0хС000 | С DriverID << 5 


sorryPicture ) ( 
521, 
(328, 367, 366, 461), 
$"1101 A000 8201 000A 0000 0000 0200 0240" 
$9800 0Е01 4801 6801 6E01 0001 4801 6Ғ01" 
$^6E01 С001 4801 6Ғ01 6E01 (000 000Ғ 0600" 
%”3С07 0000 С070 FEOO 030С 00С0 OAF 0600" 
%”1803 0000 СС30 ҒЕ00 030C 00С0 0000 0600" 
%”1803 0000 CC30 ҒС00 0100 000Ғ 0800 181Е* 
$"3DF8 1ЕЗЕ 783E F3DD F8FF 000Ғ 0800 1833" 
$^66EC 0C3B CC67 9E6C ECFF 000Ғ 0800 1833" 
%”66СС 0С33 FC79 FFEC CCFF 000Ғ 0800 1833" 
$^66CC 0C33 CO1F 860C CCFF 000Ғ 0800 1837" 
$^66CC 0С33 CC67 9E6C CCFF 000Ғ 0800 ЗСІҒ” 
$"BDFE 073Е 787C F3DF FEFF 0002 F300 Q2F3" 
$"0002 Ғ300 02F3 0008 FCOO 001С ҒЕ00 01Е1" 
$"COFE 0008 ҒС00 050С 0001 8060 COFE 0008” 
$"FCO0 050С 0001 8060 COFE 000Ғ 0800 03Ғ1" 
$"E0F3 CCF7 E3DE 7CCF 3EFF 000Ғ 0800 0108” 
$^319E 6098 E183 7609 E6FF 000Ғ 0800 0108” 
%”3186 6098 018Ғ 660Е F8FF 000Ғ 0800 0108” 
%”3186 6098 0188 6608 1EFF 000Ғ 0800 0198” 
$"319E 6098 0187 6609 E6FF 000Ғ 0800 03Ғ0” 
$“EQF3 DEF7 80FF FDEF 7CFF 0002 Ғ300 02Е3" 
$"0002 Ғ300 02F3 000С 0800 0001 СС00 GELB" 
$"00E0 ҒС00 0С08 00С0 00СС 0006 0000 6OFC" 
$"000C 0800 С000 С000 0600 0060 FCOO 0Ғ08” 
$"01EF 070С FFE6 7BFC 7C7B Ғ780 FF00 0Ғ08” 
$"0009 8СС0 9886 (098 76CD FCCO FF00 0Ғ08” 
%”0009 8СС0 E336 3098 66FD 8FCO FFOO SEGA” 
$"0009 8ССС 7836 ECFO 66C1 8СҒЕ 000Ғ 0000" 
$"098D С098 360С Ғ066 С08С 0998 000Ғ 0000" 
%”7Ғ07 FFF3 ЕҒТЕ 60FF 7BC7 9998 0009 Ғ000" 
%”0303 0000 60ЕВ 0009 Ғ000 0303 0003 COFB" 
$0009 FDOO 0307 8003 80ҒВ 0040 0083 ҒҒ” 
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Macintosh П 


The Palette Manager & Color Puzzle 


For the next two months, this column is going to be a little 
different than the previous ones. Normally a new area of Mac / 
/ programming is picked each month. That area is discussed, 
along with it's implementation and implications, and a sample 
program is given that demonstrates the concepts in action. 

This month's (much promised) column is on the Palette 
Manager, while next month's will be on using the Palette Man- 
ager to do Palette Animation. In this article, there will be a 
explanation of why the Palette Manager is needed and how it 
works. The basic Palette Manager calls will be explained. Next 
month, the sample program, PalFun, will be taken apart step by 
step, explaining the Palette Manager Animation calls and the 
special effect done using Palette Animation. 

Still, every column should have at least one example of code, 
so presented here is Color Puzzle. It was created back in the days 
when there was very little truly useful color applications or Desk 
Accessories. Two Mac-Fanatics wanted to show everyone the 
real reason they purchase their Mac //s. Their idea of program- 
ming was telling this Author that the Color Puzzle was a needed 
tool. This Author agrees with them! 


RGB vs Pixel Space 


So far almost all of the drawing explained in this column has 
been in RGB space. A program picks a specific color, consisting 
of an 8 bit Red component, an 8 bit Green component and an 8 
bit Blue component. The program then draws with this color, 
using Color Quickdraw commands, to a specific Color Graphics 
Device (ex. Apple’s Mac // Video Card/Monitor). While most 
Graphics Devices can display any possible RGB color, most 
Devices can only display a finite number of colors at any time. 
This is due to the way the memory of the Mac // Video Devices 
(ie. Screen) is structured. 

Every pixel on the screen has an associated spot in memory. 
On the older non-Color Macs, this spot in memory was a single 
bit that designated if the pixel was white or black. On the color 
Mac //, this spot in memory is a variable size, unsigned integer. 
The integer contains an index number. That number corresponds 
toa table of RGB colors (called a Color Look Up Table or CLUT) 
that the Video card maintains and uses to physically display the 
screen. If a pixel has a index of 3 in memory, that same pixel is 
displayed on the Video Card/Monitor using the 3rd color in the 
Video Card’s CLUT. Changing the pixel index, changes the 
pixel color on the screen. Color Quickdraw does it’s drawing by 
manipulation of each pixel’s index. 

Obviously the number of colors most card can display is 
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Fig. 1 Our color puzzle іп black and white! 
Pressing the option key brings up the color 
chooser. 


dependent on the amount of memory used for each pixels; 2 to the 
power of the number of bits per pixels is equal to the number of 
colors that can be displayed at one time. For example, the initial 
Apple Video Card has 4 bits per pixels and can only display 16 
colors at one time. If someone wants to upgrade the memory on 
the card using Apple's Video Expansion Kit to 8 bits per pixel, 
then the card can display up to 256 colors at one time. 8 Bits per 
pixel (256 Colors) is currently the most common configuration 
of Mac // Graphic Cards, though 24 Bit Cards may be just around 
the corner. 

The decision of what colors are to be physically displayed оп 
a card and what RGB values map into which physical color is 
handled by the Color Manager (not the Quickdraw Manager). 
When the Mac // is initially booted, the Color Manager normally 
sets the colors of each Graphics Device to commonly used colors. 
The Mac //'s defaultcolor environment (ie. settings of the CLUT) 
are sometimes called the *Apple System Colors". When Color 
Quickdraw needs to know what index corresponds to the RGB 
value it wants to draw with, itcalls the Color Manager. The Color 
Manager checks the current status of the Video Card’s CLUT and 
returns an index value. This is the index of the RGB value closest 
to the RGB color Color Quickdraw wants to draw with. There 
may not be a RGB color in the Video Card’s CLUT anywhere 
close to the requested color. The Color Manager returns the best 
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choise given the current status of the CLUT. For many applica- 
tions, best choice is good enough. However it is not hard to think 
of applications that need exact control of the colors used. If the 
program is an elaborate Drawing or Painting program, the user 
may wantto control the colors himself, allowing more greens for 
a landscrape, or more flesh tones for a portrait. If the program is 
a game, the various figures and images may have to be in a 
specific color. If the program is connected to a video input 
scanner, the program may want to set the colors of the card to 
match the colors used by the scanner. The Color Manager allows 
direct manipulation of each pixel's colors. 


Color Manager vs Palette Manager 


After praising the Color Manager for what it can do, the next 
Statement may sound a little strange; NEVER use the Color 
Manager! Instead use the Palette Manager. The Color Manager 
would be adequate to use if all programs were written to be the 
only thing running on a specific system configuration. This is 
almost never the case. Most programs have to be written to run 
on any number or size of video cards. Other code segments may 
be running at the same time that require different colors. Obvi- 
ously programs under Multifinder needs to share the colors. 
Even Desk Accessories may need specific colors. Who decides 
which colors are needed? More importantly, when there is a 
limited number of bits on the video card, who decided which 
colors are safe not to include (more than one code segment may 
want the same color). If video card's colors change, how does the 
rest of the system handle this? The Palette Manager is the 
solution for these problems. 

When using the Color Manager, the Manager is ma- 
nipulating the entire Color Table on a Specific Card (cumber- 
some). When using the Palette Manager, the Manager is con- 
cerned with groups of colors (ie. a Palette) that each specific 
window needs to display. The Palette Manager calls the Color 
Manager to select the best choice of colors for each video card (по 
matter it's size) that would make all the Palettes happy. 

To paraphrase a quote, “You can not make all the palettes 
happy all the time". However, a program can make the user 
happy all the time. Each Palette is associated with a given 
window. It is logical to give the top most Window (and it's 
associated Palette) the highest priority. This is the window the 
user iscurrently looking at. If the top most Palette is smaller than 
the number of colors on a card, other Palettes are used to select 
the remaining colors. If there are not enough colors for all the 
Palettes, the top most window has it's colors selected first. 


Using the Palette Manager 


There are many ways to create a Palette. The Color Puzzle 
uses the easiest method to understand. First a Palette Handle is 
created using NewPalette. NewPalette needs to know the 
number of entries the Palette will have, the color table it should 
use to pre-set the colors, and the Usage and Tolerance of the 
colors. Note: Entries are not really colors at this point as much 
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as there are RGB values that are requested. They are number 
from O (first entry) to N-1 (where there are N number of entries 
in the Palette). 

Color Tables are lists of RGB values that the Mac // uses to 
set various graphic data structures. When passed to NewPalette, 
the Palette entries are pre-set using the RGB colors in the table. 
Once set, the Color Table is not used by the Palette Manager or 
by that Palette Handle, and can be safely disposed of. If NIL is 
passed for the color table, the entries in the Palette are set to black. 
There are no Quickdraw calls or methods to create a color table 
other than stuffing the values into a handle. Thus NewPalette is 
normally passed NIL, and the colors are changed after the Palette 
is created, but before it is attached to a window. 

The Colors of the Palette can be set using the SetEntryColor 
call. SetEntryColor changes the RGB values of a specific entry 
inaPalette. SetEntryColor is passed the Palette Handle, an index 
to the entry (0 being the first entry, 1 being the second and so on), 
and the RGB value to change the entry to. GetEntryColor is the 
reverse call to retrieve a specific RGB value from an entry. It 
is passed the Palette Handle, an index to the entry being refer- 
enced, and the RGB variable to return the values in. 

No matter which method is used to set the Colors of the 
Entry, always set entry 0 to White (RGB $FFFF,$FFFF,$FFFF) 
and entry 1 to Black (RGB $0000,$0000,$0000). Do not set any 
other entries to exactly Black or White. If a program needs an 
almost black or white shade, use near misses (ex. 
$0001,$0000,$0000 or $FFFE,$FFFF,$FFFF). To the eye, they 
will be black or white, but will still be legal to the Palette 
Manager. 

Besides the actual RGB value, each entry has a Usage and 
Tolerance value associated with it. These values effect exactly 
how the Palette Manager selects which colors to display in a 
given instance. There are 4 type of Color Usage; Tolerant, 
Courteous, Explicit and Animation. Each Usage has a pre- 
defined constant associated. Each entry's Usage value must be 
set to one of these constants. The use of an entry's Tolerance 
value is depenent on the Usage setting. Notice that difference 
between the terms “Tolerance” and “Tolerant”. The Tolerance 
value is an attribute of an entry, while the Tolerant constant is one 
of the four type of Usage colors. 

A Tolerant Color is used when the window needs to draw a 
relatively exact RGB Color. How close of a match is needed 
between the asked for RGB color and the actual color drawn is 
dependent on the value of Tolerance. A Tolerance of 0 mean the 
program wants an exact match. If that exact color is not avaliable 
on the Video Card, then the Palette Manager will change the 
colors of the card to get that color. If Tolerance is a number, the 
Palette Manager will check the currently displayed colors on the 
card. If there is one that is close to the entries RGB value (ie. one 
where any given difference between the Red, Green or Blue 
components are less than or more than Tolerance), the Palette 
Manager will use that color and not reset the card. The majority 
of the entries in most Palettes have a Usage value of 2 (Tolerant). 

A Courteous Color is a place holder. The Tolerance value is 
ignored. The Palette Manager will not change the colors of a 
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graphic card to get this color. The Manager will deallocate (ie. 
change that color to a more needed one) other colors first when 
it is trying to find unused colors. In other words, when talking 
strictly about Courteous Colors and Color with no usage, the 
Palette Manager will deallocate RGB colors from a Video Card's 
CLUT that are non-usage Colors, before Courteous Colors. 
Tolerent color will always be deallocated last. Using Courteous 
Color is also an useful way to store RGB values that the program 
may want to use (see below). 

An Explicit Color is a convenience for programs that want 
to show what the current color environment is. Instead of having 
to use the Color Manager to find out the current color environ- 
ment, a program creates a Palette of colors of usage Explicit 
(Colors and Tolerance ignored). When drawing with Entry 
number 0, instead of drawing the RGB value of stored at Entry 
0, the color 0 of the Color Device is displayed. This is an ecellent 
method to show the current CLUT colors. Next Months PalFun 
has a window that does this. There are a number of Public 
Domain Desk Accessories that do exactly this. Such tools are 
invaluable to any programmer who is working with the Palette 
Manager. 

An Animated Color is special tool used for Palette Anima- 
tion (more next month). For now, realize that when an Animated 
Coloris allocated, that color will only appear on the Window that 
has the Palette that the color is allocated to. If one Palette 
allocated a Red Animated Entry (RGB $FFFF,$0000,$F0000), 
and then another Palette allocated a Red Tolerent Entry (Toler- 
ance 0), another Red would be added to the Video Cards color list 
instead of using the first colors. When a RGB color is drawn in 
a window, if that exact color is in the CLUT of the Video Card 
as an Animated Color, another index will be selected. 

Usage and Tolerance are set by NewPalette for the entire 
Palette or each entries Usage and Tolerance can be set with the 
SetEntryUsage. SetEntryUsage is passed the Palette Handle, 
the entry to change, and the Usage and Tolerance values to 
change the entry to. GetEntryUsage (not used in PalFun) is the 
reverse call to retrieve a specific Usage and Tolerance values 
from an entry. It is passed the Palette Handle, the entry to look 
at, and the Usage and Tolerence variables to return the values in. 

One more thing should be mentioned when talking about 
selecting colors for a Palette. All things being equal, when the 
Palette Manager wants to set the video colors of a color card 
(from the current Palette or another Palette, if there are enough 
colors on the video card), it selects them in a first-come-first- 
serve order. If there are only enough unalocated colors on the 
Color Card for half the palette, the first half gets set and the 
second must must match to the closest colors. If the colors in the 
Palette were not distributed evenly (ie. All the Oranges first, then 
then Purples then the Yellow), there would be many shades of the 
First colors (ie. Orange) and not many shades of the remaining. 
Itis bestto distribute the colors evenly over the Palette. Place the 
best 16 colors first (don’t forget color 0 should be white, and color 
1 should be black) so that the window will appears it's best on a 
4 Bitcard. If the Palette is the second window, it may get an odd 
number of color slots given to it. Make the ones given work! 
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Select all the entries so that no matter how many entries are 
selected, the window will appear at it's best. 

Once the Palette is created using NewPalette, with or with- 
out SetEntryColor, SetPalette is used to connect a specific 
window to the Palette. SetPalette makes a logical connection 
between the Palette and the Window (ie. This Palette goes with 
this Window). The callis passed the window pointer, the palette 
handle, and a boolean flag to indicate if this window needs to be 
updated whenever the colors change. 

To understand the need for an update, imagine what happens 
when another Window (and it's Palette) is selected. If there were 
enough colors on the video card for all windows to get the Colors 
they need, nothing happens, since the best colors are already 
selected. If this is not the case (ie. small number available colors 
on the card and a large number of colors in the window), the 
Palette Manager changes the video card's colors to reflect the 
change in Palette priority. On the video card, RGB values that are 
used to display some pixels a certain color are suddenly changed. 
A globe that was a shade of green before, may suddenly be a 
shade of brown. There still may a different green that would be 
a better green to draw with, so the window should be redrawn. 
This way, the window will look it's best no matter what the 
current color environment is. Generally all Windows with 
associated Palettes need to be redrawn when the color selection 
changes. If the redraw takes too long, or the window has only 
Animated Colors (more next week on why), then the update flag 
does not need to be set. Remember this update event is caused by 
the Palette Manager; a program does not have to have any special 
code to enact it. 

If at any time in the program after the Palette is associated 
with a window (using SetPalette), an Palette entry's Color, Usage 
or Tolerance is changed using SetEntryColor or SetEntryUsage, 
ActivatePalette (not used in PalFun) needs to be called. This 
routine is normally called by the Window Manager whenever 
window status changes (ie. new window comes to front). Acti- 
vatePalette is simply passed the window of the Palette that 
changed, and it will check and handle changing any color on any 
color cards. 

When drawing to a Window that has a Palette associated 
with it, normal Color Quickdraw commands can be used. This 
involves setting numerous RGB variables and passing them to 
Quickdraw calls (ex. Red Globe, Green Globe). Then Color 
Quickdraw calls the Color Manager to pick a close index. 
Usually the window already knows which colors to use. The 
entries in the Palette for each window are the colors that are 
usually drawn on the windows.  PmForeColor and 
PmBackColor are just like their Color Quickdraw counterparts 
(RGBForeColor and RGBBackColor); they set the Foreground 
color and Background color of a Color Port. They are passed the 
number of some entry in the Palette and set the foreground or 
background color to the RGB value (ex. Blue Window). This is 
the only way that an Animated Color or an Explicit Color can be 
drawn with. Even if the Palette Manager is not used in a program 
to change the environment, the use of Courteous Colors and the 
PmForeColor/PmBackColor calls can simplify coding. 
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Calling NewPalette, SetEntryColor and Зе Раеце is a good 
method to use if the RGB entries have to be calculated at run time, 
and are not known in advance. However there is a simpler 
method if the colors for a window/Palette are known in advance. 
Create the Window using a ‘WIND’ resource and the GetWin- 
dow call. Also create a resource where the type is “ріш” and the 
ID number is the same as the ‘WIND’ resource. This “ріш” 
resource has the Palette information for the Window. When the 
Window iscreated in a program, the associate Palette is automati- 
cally created and attached to the window. Using this Method 
with the PmForeColor/PmBackColor calls place the colors of 
some applications outside the code section for easy editing with 
ResEdit or some other tool (similar to the reason most program- 
mers place the Text information outside the code section). The 
format of a “рін” resource is: 


; Bytes CINTEGER) 


14 Bytes (set 0) 


umber Colors 
Internal Data 
(for each Color) 


Color 6 Bytes (RGB Value/3 INTEGERS) 
Usage 2 Bytes CINTEGER) 
Tolerance 2 Bytes CINTEGER) 


Internal Data 6 Bytes (set 0) 


Color Puzzle 


The sample code, Color Puzzle, use the Palette Manager to 
help maintain the colors of each square. It functions like the 
traditional Puzzle from Apple with some added features. Open- 
ing the Desk Accessory with the Option Key down creates a BIG 
puzzle (for those long phone calls). Clicking опа Square with the 
Option Key Down will allow the user to change the colors used 
by the Puzzle. These changes are also saved to disk, so the user 
will have to live with what he created. Enjoy! 


Last Comments 


Thanks for all the comments about the various areas/pro- 
grams discussed in this column. This Author is always open to 
contacts from other Mac programmers! 

PalFun, next month's sample program, uses most of the 
Palette Manager calls explained here. It also uses many of the 
Animation calls that will be covered next month. In the mean- 
time, experiment! To develop a feel for how the Palette Manger 
Works, it is best to manipulate various windows and see how the 
Palette Manager reacts. 


( Color Puzzle DA by Steve Sheets 12/09/87 ) 
| Desk Accessory to show Puzzle іп Color on Мас //. 


UNIT ColorPuzzleDA; 
INTERFACE 
FUNCTION Main CtheDCE : DCtIPtr; 
IOPB : ParmBlkPtr; 
driveCall : Integer) : OSErr; 


IMPLEMENTATION 
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CONST 


DriverOpen = 0; 
DriverPrime = 1; 
DriverControl = 2; 
DriverStatus = 3; 
DriverClose = 4; 


dCtlEnable = 10; 
kLine = 18; 
Edge = 10; 
xSize = 30; 
ySize = 30; 
voff = -12; 


kxTiles 
kyTiles 


4; 
4; 


optxTiles = 10; 
optyTiles = 10; 


MaxTiles = 10; 
MaxNum = 100: 
RGBMax = 192; 


ResT = ‘RGBs’; 
pnTolerant = $0002; 
HelpWait = 240; 


Flash = 60; 
kWhite = 0; 
kBlack = 1; 


SerCount = 2000; 
OptScrCount = 10000; 


(ОА internal variable stored as a single Handle (the Picture, 
the Window} 

and a Rectange the size of the Picture).) 
TYPE 


BoardData = PACKED ARRAY[1. .МахМит] OF integer; 


PuzzleDate = RECORD 
myPal : handle; 

myID, xBig, yBig, numTiles, xTiles, yTiles : 
PuzzleWindow : WindowPtr; 
ColorFlag : Boolean; 
Normal : boolean; 
Board : BoardData; 

END; 
PuzzlePtr = ^PuzzleData; 
PuzzleHandle = ^PuzzlePtr; 


integer; 


RGBColor = RECORD 
red : INTEGER; ( magnitude of red } 
green : INTEGER; ( magnitude of green } 
blue : INTEGER; ( magnitude of blue ) 
END; 


(Format of RGB resource where colors are stored between 
boots.). 


RGBData = PACKED ARRAYI2..RGBMax] OF RGBColor; 
RGBPtr = “RGBData; 
RGBHandle = ^RGBPtr; 


(Inline Palette Manager & Color Picker calls) 


FUNCTION GetColor (where : Point; 


prompt : Str255; 
inColor : RGBColor; 
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VAR outColor : RGBColor) : BOOLEAN; BEGIN 


INLINE СТ : CT + 1; 
$3F3C, $0009, $482E; IF CCCCT - 1) DIV xTiles) © Rw) OR CCT > 
numTiles) THEN 
PROCEDURE PmForeColor CdstEntry : INTEGER); UnLegal := true; 
INLINE END; 
$4497; 33 
BEGIN 
PROCEDURE ActivatePalette CsrcWindow : WindowPtr); СТ := СТ - xTiles; 
INLINE IF (CT < 1) THEN 
$AA94; UnLegal := true; 
END; 
PROCEDURE PmBackColor (dstEntry : INTEGER); 4: 
INLINE BEGIN 
$AA98; CT := CT + xTiles; 
IF (CT > numTiles) THEN 
FUNCTION NewPalette Centries : INTEGER; UnLegal := true; 
srcColors : handle; END; 
srcUsage, srcTolerance : INTEGER) : handle; OTHERWISE 
INLINE UnLegal := true; 
$AA9 1; END; 
END; 
PROCEDURE SetPalette CdstWindow : WindowPtr; 
srcPalette : handle; (DA Open routine: ) 
cUpdates : BOOLEAND; FUNCTION Open CtheDCE : ОСИР4г) : OSErr; 
INLINE VAR 
$4495; theE : OSErr; 
thePuzzle : PuzzleHandle; 
PROCEDURE DisposePalette (srcPalette : handle); OldPort : GrafPtr; 
INLINE 
$4493; (Returns true if the Mac had Color Quickdrew.) 
FUNCTION ColorQDExists : boolean; 
(Create а Color Window.) CONST 
FUNCTION NewCWindow CwStorage : Ptr; ROM85Loc = $28E; 
boundsRect : Rect; TwoHighMask = $С000; 
title : Str255; TYPE 
visible : BOOLEAN; WordPtr = ^INTEGER; 
procID : INTEGER; VAR 
behind : WindowPtr; Wd : WordPtr; 
goAwayFlag : BOOLEAN; BEGIN 
refCon : LONGINT) : WindowPtr; Wd := POINTERCROM85Loc); 
INLINE ColorQDExists := (BitAnd(Wd^, TwoHighMask) = 0); 
$AA45; END; 
PROCEDURE SetEntryColor CdstPalette : Handle; (Is Option Key not Down?) 
dstEntry : INTEGER; FUNCTION IsOptNotDown : BOOLEAN; 
srcRGB : RGBColor); VAR 
INLINE theMap : KeyMap; 
$A49C; BEGIN 
GetKeysCtheMap); 
PROCEDURE GetEntryColor (srcPalette : Handle; IsOptNotDown := NOT BitTstC@theMap(1], 29); 
srcEntry : INTEGER; END; 
VAR dstRGB : RGBColor); 
INLINE {Scrambles the Puzzle info.) 
$AAQB; PROCEDURE ScrambleBoard; (LATER) 
VAR 
(Procedure to check if move is legal, if so, returns move.) count, Dir, CurPos, NewPos, HoldPos, Sc : integer; 
PROCEDURE DoDir (Dir, xTiles, nunTiles : integer; UnLegal : boolean; 
VAR UnLegal : boolean; BEGIN 
VAR CT : integer); WITH thePuzzle^^ DO 
VAR BEGIN 
rw : integer; FOR count := 1 ТО nunTiles DO 
BEGIN Board(count] := count; 
UnLegal := false; 
ги := (CT - 1) DIV xTiles); CurPos := numTiles; 
CASE Dir OF IF Normal THEN 
15 Sc := ScrCount 
BEGIN ELSE 
CT := CT - 1; sc := optScrCount; 
IF ССССТ - 1) DIV xTiles) © Rw) OR ССТ < 1) THEN FOR count := 1 TO sc DO 
UnLega] := true; BEGIN 
END; Dir := (Random MOD 4) + 1; 
2: ВЕРЕАТ 
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NewPos := CurPos; 
Оо0ігС0іг, xTiles, numTiles, 
UnLegal, NewPos); 
IF UnLega! THEN 
BEGIN 
Dir := Dir + 1; 
IF Dir » 4 THEN 
Dir := 1; 


END; 
UNTIL NOT UnLegal; 


HoldPos := Board[CurPos]; 
Воага(СигРов1 := Board(NewPos 1; 
Board[NewPos] := HoldPos; 
CurPos := NewPos; 
END; 
END; 
END; 


(Handle Opening already open windows Cie. either move the DA 
to the front) 
(of the screen or scramble the board).) 
PROCEDURE DAReset; 
VAR 
tmpRect : Rect; 
BEGIN 
thePuzzle := PuzzleHandleCtheDCE^ .dCt1Storage); 
HLockCtheDCE* . dCt Storage); 


WITH thePuzzle^^ DO 
BEGIN 


IF PuzzleWindow = FrontWindow THEN 
BEGIN 
ScrambleBoard; 
SetPortCPuzzleWindow); 
SetRect(tmpRect, Ø, 0, xBig, uBig); 
InvalRectCtmpRect 2; 
END 
ELSE 
SelectWindowC(PuzzleWindow); 


HUnLock( theDCE" .dCt1Storage); 
END; 


(Initialize the DA’s internal data Cincluding creating the 
Data Handle, the Window) 
( (Color if needed) and the Rectange the size of the Ріс- 


ture?) 
PROCEDURE DAInit; 
VAR 
tmpRect : Rect; 
insideWindow : WindowPeek; 


(Set Puzzle Pal entry to this RGB color) 
PROCEDURE SetPuzzlePal CN, R, 6, B : integer); 


VAR 
С: RGBColor; 

BEGIN 

C.red := г; 

C.green := 6; 

C.blue :- b; 

SetEntryColor(thePuzzle**.MyPal, n, С); 
END; 


(Sets the Colors for Puzzle.) 
PROCEDURE SetPuzzleColor; 
VAR 
count : integer; 
С: RGBColor; 
RGBH : RGBHandle; 
BEGIN 
WITH thePuzzle** DO 
BEGIN 
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SetPuzzlePal(kWhite, $FFFF, $FFFF, $FFFF); 
SetPuzzlePal(kBlack, 0, 0, 0); 


RGBH := POINTERCGetResource(ResT, MyID)); 
IF RGBH = NIL THEN 
BEGIN 
FOR count := 2 TO numTiles DO 
CASE count MOD 6 OF 
0 А 


SetPuzzlePal(count, $FFFF, 0, 0); 
M une 0, $FFFF, 0); 
E 0 0, 0, $ЕРЕР); 
M $FFFF, $FFFF, 0); 
SetPunePa солі 0, $FFFF, $FFFF); 


SetPuzzlePal(count, $FFFF, 0, $FFFF); 
OTHERWISE 


END; 
SetPuzzlePalCnumTiles + 1, $8888, $8888, $8888); 
SetPuzzlePal(numTiles + 2, $FFFF, 0, $FFFF); 
END 
ELSE 
BEGIN 
FOR count := 2 TO nunTiles + 2 DO 
BEGIN 
С :- RGBH^^[count 1; 
SetPuzzlePelCcount, C.Red, C.Green, C.Blue); 
END; 

Re leaseResource(POINTERCRGBH)); 
END; 
END; 

END; 


BEGIN 

theDCE* .dCtlStorege := NewHandle(SizeOf (PuzzleData)); 
HLock( theDCE* .dCt1Storage); 

thePuzzle := PuzzleHandle(theDCE* .dCt1Storage); 


WITH theDCE^, thePuzzle** DO 
BEGIN 
myID := theDCE*^ .dCtlRef Num; 
IF nyID » 0 THEN 
myID := -myID; 
myID := $6000 + 32 * (-1 - muID); 


Normal :- IsOptNotDown; 
IF Norma! THEN 
BEGIN 
xTiles := kxTiles; 
ylTiles := kyTiles; 
D 


ELSE 
BEGIN 
myID := ту + 1; 


xTiles := optxTiles; 
yTiles := optyTiles; 
END; 
numTiles := xTiles * yTiles; 
xBig := (xTiles * xSize) + (2 * Edge); 
yBig := (yTiles * uSize) + (2 * Edge); 


ColorFlag := ColorQDExists; 
tmpRect.top := 40; 
tmpRect. left := 40; 


tmpRect.right := tmpRect.left + xBig; 
tmpRect.bottom := tmpRect.top + yBig; 
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IF ColorFlag THEN 

BEGIN 

PuzzleWindow := NewCWindow(NIL, tmpRect, 
‘Color Puzzle’, true, rDocProc, Pointer(-1), True, 9); 

myPal := NewPaletteCnumTiles + 4, NIL, 
pnTolerant, 0); 

SetPuzzleColor; 

SetPaletteCPuzzleWindow, myPal, true); 


PuzzleWindow := NewWindowCNIL, tmpRect, 


‘B/W Puzzle’, true, rDocProc, Pointer(-1), True, 0); 
myPal := NIL; 
END; 
ScrambleBoard; 
insideWindow := WindowPeekCPuzzleWindow); 
insideWindow^ .windowKind := dCtlRefNum; 
dCtlWindow := Ptr(PuzzleWindow); 


END; 
HUnLock( theDCE* .dCt Storage); 
END; 


(Main Body of the Open Routine. If the DA is not open, 
initialize Puzzle.) 
( If there is а puzzle, scamble it.) 
BEGIN 
GetPortColdPort); 
theE := noErr; 


IF theDCE^.dCtlStorage = NIL THEN 
DAInit 

ELSE 
DAReset ; 


Open := theE; 
SetPortColdPort?; 
END; 


(DA’s donothing Prime Routine.) 
FUNCTION Prime CtheDCE : DCtiPtr; 
IOPB : ParmBlkPtr) : OSErr; 
BEGIN 


Prime :- noErr; 


END; 


(DA’s Control Routine: Handles Update & Mousedown events. If 
the event is an) 
( Update, drew the Puzzle. If it is а mousedown in the 
contents of the window,) 
( check if the option is down. If so, reset that Tiles 
color. If not, see if that) 
( is а legal move Cand move if it is). If the event is a 
keydown, end & help key) 
( (?,/,h,H,Help) was pressed, display the dedication (who 
needs help for) 
( а Puzzle?).} 
FUNCTION Control CtheDCE : DCtIPtr; 
IOPB : ParmBlkPtr) : OSErr; 
CONST 


accEvent = 64; 
accUndo = 68; 
accCut = 79; 
accCopy = 71; 
accPaste = 72; 
accClear = 73; 

VAR 
theEvent : EventRecord; 
thePuzzle : PuzzleHandle; 
eWindow : WindowPtr; 
tmpPat : Pattern; 
oldPort : GrafPtr; 
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(Given count, return Rect holding count.) 
PROCEDURE GetCountRect (n : integer; 
VAR R : rect); 


VAR 
xn, yn : integer; 
BEGIN 
WITH thePuzzle^^ DO 
BEGIN 
xn := (((п - 1) MOD xTiles) * xSize) + edge; 
n := («n - 1) DIV xTiles) * ySize) + edge; 


SetRect(R, xn + 1, yn + 1, xn + xSize, yn + ySize); 


END; 
END; 


(Given count, ColorFlag & Rect, drew Tile there.) 
PROCEDURE DrawTile (N : integer; 
VAR R : rect); 
VAR 


S : str255; 
BEGIN 


WITH thePuzzle^* DO 
BEGIN 
IF (М = numTiles) AND (NOT ColorFlag) THEN 
BEGIN 
ЕгазеКес{ CR); 
Stuf fHexC@tmpPat, '8800220088002200’); 
FillRect(R, tmpPat); 


IF ColorFlag THEN 
PmBackColor(N + 1); 


EraseRect(R); 


IF (М «© numTiles) THEN 
BEGIN 
NumToString(N, S); 
MoveTo(R. left + ((хбіге - 
StringWidth(S)) DIV 2), R.bottom + vOff); 
DrawString(S); 
END; 
END; 
END; 
END; 


(Draws the board. } 
PROCEDURE DrawBoard; 
VAR 
count, yn, xn : integer; 
tmpRect : rect; 
BEGIN 
WITH thePuzzle^^ DO 
BEGIN 
IF ColorFlag THEN 
PnForeColor(numTiles + 2) 
SE 
BEGIN 

StuffHexC@tmpPat, *0077007700770077'); 

PenPatCtmpPat); 

END; 
SetRect(tmpRect, 0, 0, xBig, edge); 
PaintRect(tmpRect); 
SetRect(tmpRect, 0, 0, edge, yBig); 
PaintRect(tmpRect); 

SetRectCtmpRect, xBig - edge + 1, Ø, xBig, yBig); 
PaintRect(tmpRect); 

SetRect(tmpRect, 0, yBig - edge + 1, xBig, yBig); 
PaintRect(tmpRect ); 


IF ColorFlag THEN 


PmForeColor(kBlack) 
ELSE 
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ВЕСІН 
StuffHex(8tmpPat, 'FFFFFFFFFFFFFFFFFFF ^); 
PenPatCtmpPat); 
StuffHexCetmpPat, '2000000000000000 °); 
BackPat(tmpPat); 
END; 
yn := (yTiles * ySize); 
xn := (xTiles * xSize); 
FOR count := 0 TO xTiles DO 
BEGIN 
MoveToCEdge, Edge + (count * uSize)); 
LineCxn, 0); 


END; 
FOR count := 0 TO yTiles DO 
BEGIN 
МоуеТо(Едде + (count * xSize), Edge); 
Line(0, un); 


END; 

TextFace( [shadow 12; 

FOR count := 1 ТО nunTiles DO 
BEGIN 


GetCountRect(count, tmpRect); 
DrawTile(Board{count], tmpRect) 
END; 
Тех{Расе( (1); 
ЕМО; 


2 


END; 


(Handles the Move.) 
PROCEDURE DoMove (T : integer); 
VAR 
CanMove, UnLegal : boolean; 
tmpRect : Rect; 
CT, temp, nn, Rw, Dir : integer; 
Buf : ARRAY[1..MaxTiles] OF integer; 
BEGIN 
WITH thePuzzle^^ DO 
BEGIN 
СапМоуе := false; 
Ки := ((Т- 1) DIV xTiles); 


біг := 0; 

КЕРЕАТ 
UnLegal := false; 
Dir := Dir + 1; 


nn := 0; 
СТ := T; 
КЕРЕАТ 


nn := nn + 1; 
Buf [nn] := CT; 
IF Board[CT] = numTiles THEN 


BEGIN 
IF nn = 1 THEN 
UnLegal := true 
ELSE 
CanMove := true; 
END 
ELSE 


DoDir(Dir, xTiles, numTiles, 
UnLegal, CT); 
UNTIL CanMove OR UnLegal; 
UNTIL CanMove OR (Dir ›= 4); 


IF CanMove THEN 


BEGIN 
TextFace( [shadow 1); 
FOR temp := пп DOWNTO 2 DO 


BEGIN 
Board[Buf[temp]] := Board(Buf [temp - 11); 
GetCountRect(Buf [temp], tmpRect); 


DrawTileCBoard[Buf (+етр 71, tmpRect) 


END; 
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Board(Buf{1]] := numTiles; 
GetCountRectCBuf [1], tmpRect); 
DrewTileCBoardi[Buf [11], tmpRect); 
TextFaceCL 1); 


nn := 0; 
КЕРЕАТ 
nn := nn + 1; 
UnLegal := (Boerdínn] © nn); 
UNTIL (nn = numTiles) OR UnLegal; 
IF NOT UnLegal THEN 
BEGIN 
SetRect(tmpRect, 0, 0, xBig, uBig); 
IF Normal THEN 
temp := Flash 
ELSE 
temp := Flash DIV 2; 
FOR nn := 1 TO temp DO 
InvertRect(tmpRect); 
SusBeep( 1); 
END; 
END; 
END; 


(Save new Color settings to resource) 
PROCEDURE SaveColor (T : integer; 
C : RGBColor); 
VAR 


RGBH : RGBHandle; 
temp : integer; 
BEGIN 
RGBH :- POINTER(GetResource(ResT, 
thePuzzle** .MyID)); 
IF RGBH ‹› NIL THEN 
BEGIN 
RGBH**{T] := С; 


ChangedResourceChandleCRGBH2); 
Wr iteResourceChandle(RGBH)); 
ReleaseResourceChandleCRGBH)); 
END; 
END; 


(Handles changing the Color.) 
PROCEDURE DoColor (T : integer); 
VAR 
P : point; 
tmpRect : Rect; 
N : integer; 
C, NewC : RGBColor; 
BEGIN 
WITH thePuzzle^^ DO 
IF (T >= 1) AND (T <= nunTiles + 1) THEN 


0; 
0; 
numTiles + 1 THEN 

М := numTiles + 2 
ELSE 

М := Воага[Т] + 1; 
GetEntryColor(myPal, М, C); 


IF GetColor(P, “Pick the Color for this 
tile:’, C, NewC) THEN 


ж“: 
-ч 
u 


BEGIN 
SetEntryColor(myPal, М, NewC); 
saveColor(N, NewC); 
ActivatePaletteCPuzzleWindow); 
SetRectCtmpRect, 0, 0, xBig, uBig); 

InvelRectCtmpRect); 

END; 

END; 
END; 
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(Is the Option key down?) 
FUNCTION OptDown : boolean; 
BEGIN 


OptDown := (BitAndCoptionKey, theEvent.modif iers) € 0); 


END; 


(Handles & Mouse Down.) 
PROCEDURE DoMouse (P : point); 
VAR 
R : Rect; 
C, М: integer; 
BEGIN 
WITH thePuzzle^^ DO 
BEGIN 


Global ToLocal(P); 
SetRect(R, 0, 0, xBig, yBig); 
IF PtInRect(P, R) THEN 
BEGIN 
N := numTiles + 1; 
С := 0; 
КЕРЕАТ 
С := Ç + 1; 
GetCountRectCC, R); 
IF PtInRect(P, R) THEN 
М-С; 
UNTIL СМ <= numTiles) OR (C = numTiles); 


IF OptDown THEN 
BEGIN 
IF ColorFlag THEN 
DoColor(N); 


END 
ELSE IF (М <= numTiles) THEN 
DoMove(N); 
END; 
END; 
END; 


(Handles a Key Down Cie. Help).} 
PROCEDURE ПоКеу; 
VAR 
tempVirtual, v, dv, c : integer; 
tempChar : char; 
tempRect : rect; 
11: longint; 
count : integer; 
tmpPat : Pattern; 


PROCEDURE ColorBurst (S : str255); 
VAR 
ch : cher; 
nn : integer; 
BEGIN 
WITH thePuzzle^^ 00 
BEGIN 


MoveTo((xBig - StringWidth(S)) DIV 2, м); 


у := dv + v; 
IF ColorFlag THEN 
FOR nn := 1 TO Length(S) DO 
BEGIN 
ch := S[nn]; 
PmForeColor(C); 
c:=ct 1; 
IF c = (nunTiles + 2) THEN 
С := 2; 
DrawChar(ch); 
END 
ELSE 
DrawString(S); 
END; 
END; 
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BEGIN 
WITH thePuzzle^^ DO 
BEGIN 
tempChar := Chr(theEvent.message MOD 256); 
tempVirtual := CtheEvent.message DIV 256) MOD 256; 
IF CtempVirtual = $72) OR CtempChar IN (7?”, 
‚ 'H', 993 THEN 
EGIN 
SetRectCtempRect, 0, 0, xBig, uBig); 
IF ColorFlag THEN 
BEGIN 
FOR count := 2 TO NumTiles DO 
BEGIN 
PmBackColorCcount); 
EraseRect( tempRect); 
InsetRectCtempRect, 1, 1); 
END; 
PmBackColor (kWhi te); 
EraseRect(tempRect); 


BEGIN 
StuffHexC@tmpPat, 'FFFFFFFFFFFFFFFFFFF ^); 
PenPatCtmpPat); 
StuffHexCetnpPet, '0000000000000000 '); 
BackPat( tmpPat); 
FOR count := 2 ТО NumTiles 00 
BEGIN 
IF (count MOD 2 = 0) THEN 
PaintRectCtempRect) 
ELSE 
EreseRect(CtempRect); 
InsetRectCtempRect, 1, 1); 


END; 
EraseRect(tempRect); 
END; 


dv := kLine; 
у := tempRect.top + dv; 
С: 


= 2, 


ColorBurstC'Color Puzzle 1.0’); 
ColorBurst(C'by^); 

ColorBurst('Steve Sheets ‘); 
ColorBurst( ‘dedicated to’); 
ColorBurst( ‘Fred Bockman’); 
ColorBurst( ‘Steve Levinthal *); 
DelayCHelpWait, 11); 
SetRectCtempRect, 0, 0, xBig, yBig); 
IF ColorFlag THEN 


PmBackColor(kWhi te); 
EraseRect(tempRect ); 
InvalRect(tempRect ); 
END 
END; 
END; 
BEGIN 


Control := noErr; 


GetPortColdPort); 

HLockCtheDCE^ .dCt1Storage); 

thePuzzle :- PuzzleHandle(CtheDCE* . dCtlStorage); 
SetPortCthePuzzle**^ .PuzzleWindow); 


CASE IOPB^.csCode ОҒ 
accEvent : 
(Ме got an event.) 
BEGIN 


BlockMoveCIOPB* . іоМіѕс, @theEvent, 


SizeOf CtheEvent?); 


CASE theEvent.whet OF 
updateEvt : 
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BEGIN 
Beginupdate(WindowPtr(theEvent . message); 
SetPor tCWindowP tr( theEvent .message)); 
DrawBoard; 
EndUpda te (WindowPtr( theEvent .message )); 
END; 
mouseDown : 
IF FindWindow( theEvent.where, awindow) 
IN [inSysWindow, inContent] THEN 
IF aWindow = 
thePuzzle^^.PuzzleWindow THEN 
DoMouseCtheEvent .where ); 
keyDown, autoKey : 
DoKey; 
OTHERWISE 
Е ЕИ; (End of event CASE statement) 
ND; 
accUndo, accCut, accCopy, accPaste, accClear : 
SysBeep( 1); 
OTHERWISE 
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HUnLock CHandle( thePuzzle)); 
SetPortColdPort); 
END; 


(DA’s donothing Status Routine.) 
FUNCTION Status CtheDCE : DCtiPtr; 
IOPB : ParmBlkPtr) : OSErr; 
BEGIN 


Status := noErr; 
END; 


ras Close Routine: Dispose of the Palette, the Window Ptr & 
the 
( Data Handle.) 
FUNCTION Close CtheDCE : DCtiPtr; 
IOPB : PermBlkPtr) : OSErr; 
VAR 


thePuzzle : PuzzleHandle; 
BEGI 
Close := noErr; 


HLockCtheDCE* .dCt1Storage); 
thePuzzle :- PuzzleHandleCtheDCE^ .dCt Storage); 
WITH thePuzzle** DO 
BEGIN 
IF myPal © NIL THEN 
DisposePalette(myPal); 
DisposeW indow(Puzz leW indow); 


HUnLock( theDCE* .dCt]Storage); 


IF theDCE^ .dCtlRefNum < Ø THEN 
HPurgeCHandleCtheDCE* . dCt1Dr iver 22; 


theDCE* .dCt Window := NIL; 
DisposHandleCtheDCE* .dCt1Storage); 
theDCE^ .dCtlStorage := NIL; 
END; 


(Standard LSP Desk Accessory Main Routine) 
FUNCTION Mein; 
BEGIN 
CASE driveCall OF 
DriverOpen : 
Main := OpenCtheDCE); 
DriverPrime : 
Main := PrimeCtheDCE, IOPB); 
DriverControl : 


BitClrCétheDCE^.dCtlFlags, 15 - dCtlEnable); 
Main :- ControlCtheDCE, 10РВ); 
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BitSetC@theDCE* .dCtIFlags, 15 - dCtlEnable); 


DriverStatus : 
Main := Status(theDCE, І0РВ); 
DriverClose : 
Main := CloseCtheDCE, ІОРВ); 
END; 
END; 


END. 


/* 


ColorPuzzle.r - Resources Гог the Color Puzzle DA 
used to store the Palette RGB values between boots. 


Steve Sheets 2/3/88 
All rights reserved. 


----------------Х/ 


“ілсішде “Types.r’ 


data ‘RGBs’ (-16000) ( 


); 


$^4308 95AE FFFF FFFF 8659 9785 4ECA 8BFF” 
$"06E2 FFFF FFFF 0000 FFFF 0000 FFFF 0000" 
$^FFFF FFFF FFFF 04Е9 @EAE 0000 0000 FFFF^ 
$"0000 FFFF 0000 FFFF 80С7 061A FFFF 0000" 
$^FFFF 2204 827A D4FF FFFF 2403 77A3 A426" 
%”60С4 FFFF COFF 6091 0001 8888 8888 8888" 
%”5282 2638 FFFF” 


data ‘RGBs’ (-15999) ( 


$'A589 8160 O7AB FFFF 038В 0580 FFFF 0405" 
%8205 FFFF 0001 FDBF FFFF 0518 FFFF 882A” 
$0961 FFFF 0854 828F FFFF 051Е FB9B FFFF” 
$"075A FFFF 7СҒй 0518 FFFF 0282 0768 FFFF” 
$0230 8533 FFFF 046Е ҒАВ5 8666 ØCCD FFFF” 
$°FFFF 68F6 68F6 FFFF БАВА B7C3 FCOB 6556" 
$“FFFF ACFC 63C2 FFFF 6С10 6680 FFFF 6316" 
$*B628 FFFF 6307 FFFF FFFF 6556 FFFF В60Е” 
%”6890 FFFF 714E ВОВЕ FFFF 6661 FFFF F73D^ 
%”66АЗ FFFF ADC3 6680 0062 ЕЙІҒ FFFF 8564" 
$^19079 FFFF FFFF 5420 A5B9 8160 07AB FFFF” 
%”0388 0580 FFFF 0405 8295 FFFF 0001 FD8F” 
$“FFFF 0518 FFFF 882A 0961 FFFF 0854 828Ғ” 
$/FFFF Ø51F FBOB FFFF 075A FFFF 7СҒ0 0518” 
$°FFFF 0282 0768 FFFF 0230 8533 FFFF 046Е” 
%”ҒАВ5 8666 ØCCD FFFF FFFF 68F6 68F6 FFFF^ 
$"6ABA B7C3 FC9B 6556 FFFF ACFC 63C2 FFFF^ 
%”6С10 6680 FFFF 6316 B628 FFFF 6307 FFFF” 
$“FFFF 6556 FFFF В60Е 6890 FFFF 714E ВОВЕ“ 
$^FFFF 6661 FFFF Ғ730 66A3 FFFF ADC3 6680” 
$^0062 ЕЙІҒ FFFF 8564 1979 FFFF FFFF 5420” 
%”А5В9 8160 07AB FFFF 038В 0580 FFFF 0405" 
%”8205 FFFF 0001 FDBF FFFF 0518 FFFF 882A” 
%0061 FFFF 0854 828F FFFF 0512 FBOB FFFF^ 
%”075А FFFF 7CFØ 0518 FFFF 0282 0768 FFFF” 
%”0230 8533 FFFF 046Е ҒАВ5 8666 0СС0 FFFF^ 
$°ЕЕЕЕ 68F6 68F6 FFFF БАВА B7C3 FCOB 6556" 
$°FFFF ACFC 63C2 FFFF 6С10 6680 FFFF 6316" 
%”В628 FFFF 6307 FFFF FFFF 6556 FFFF В60Е” 
%”6890 FFFF 714E ВОВЕ FFFF 6661 FFFF Ғ730* 
%”6бАЗ FFFF ADC3 6680 FFFF FFFF FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF 4482 В109 0000" 
$'0000 FFFF 0000 FFFF 0000 FFFF FFFF 0000" 
$ЕРЕЕ 0000 FFFF 0000 FFFF FFFF FFFF 0000" 
$'0000 0000 0000 FFFF 0000 FFFF 0000 FFFF" 
$°FFFF 0000 FFFF 0000 FFFF 0000 FFFF FFFF^ 
$"FFFF 0000 0000 0000 0000 FFFF 0000 FFFF" 
$'0000 8888 8888 8888 1303 9828 ҒЕҒҒ” 
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Macintosh II 


Palette Animation 


PalFun: an Example of Palette 
Manipulation 


Last month's column explained the ba- 
sics of the Palette Manager, the new Toolbox 
calls designed to handle the color environment 
of the Mac //. To fully understand this month's 
column, the reader will have to have either 
read the previous article and/or have worked 
with the Palette Manager on his own. Hope- 
fully any new ideas/examples will be ex- 
plained this month, but the reader must have a 
certain level of knowledge of Macintosh // 
Color to start with (this author hates 2-part TV 
Shows which spend most of the second part rehashing the events 
of the first half). This month's article will explain the idea of 
Palette Animation, or how to directly manipulate colors in the 
Palette to change shapes on the Macintosh // screen. The first 
portion of this article will describe the concepts involved in 
Palette Animation. The second section will describe special 
effect techniques that can be used with Palette Animation. The 
last section is an explanation of this month's sample program, 
PalFun. 


Palette Animation: Changing the Color 
Environment 


Imagine a sample Macintosh // screen, using the information 
described last month. The color screen has several windows on 
it, each one having a Palette and a group of colors that it wants to 
draw with. The top most window gets first choice of colors. 
Based on how many colors it wants and the tolerance of each 
color (ie. how picky it is in finding a closely matching color), the 
Palette Manager has changed certain colors in the CLUT (Color 
Look Up Table) of the video card. If there are any entries in the 
CLUT unused (ie. not reserved by someone), the next lower 
Window gets it's choice of Colors, and so on, and so on. 

At some point, the number of available entries on the video 
card will run out. If there are any windows with Palette that have 
not gotten a chance to allocate entries, they will just have to make 
do (ie. use the given colors in the color environment). If there are 
several windows, this may happen to the bottom most window, 
or it may happen to the top most window if there are not very 
many entries in the CLUT of the video card. 

Back to imagining the sample Macintosh // screen with 
multiple windows. Imagine that each one has a certain shade of 
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PalFun Application 
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Fig. 1 Rainbow function animates color palette 


Red it wants to display. The first window get it's exact Red 
$FFFF,$0,$0 (ie. the Palette Manager changes the CLUT of the 
video card so that some entry on it has this value). The second 
window happens to need the exact shade of Red $FFFF,$0,$0. 
Since the second window is more than happy to use the shade 
allocated by the first window, no entries are use by the second 
window to describe this red. The third window wants it's own 
shade of Red $CCCC,$0,$0, so it is allocated a color entry (there 
are still enough left). Finally the last window wants a Red shade 
of SEEEE,$0,$0, but there are no color entries left unallocated, 
so it does not change the Color environment. 

When each Window tries to draw it's own shade of Red, it 
has to use the Colors available on the card (assume no other 
shades of Red on the video card in this example). Windows one 
and two use the $FFFF,$0,$0 shade of red, while Window three 
uses the $CCCC,$0,$0 shade. When window four tries to draw 
it's shade, Color Quickdraw will probably pick $FFFF,$0,$0 to 
color with. The selection of which color is actually going to be 
drawn with is transparent to the programmer; Color Quickdraw 
calculates the best match, not the program. 

Remember that the CLUT contains the information of what 
colors are actually being displayed on the screen. The video card 
uses aRAM buffer to model the screen. Each pixel on the screen 
matches a value in the buffer. The buffer does not have a RGB 
value for each pixel, instead it has a pixel value. The size (in bits) 
of this value is fixed at any given moment, but can be changed 
depending on how much memory is allocated to the buffer (done 
by the Monitor portion of the Control Panel). So called pixel 
values in the buffer correspond to an entry in the video card 
CLUT. Thus a green pixel on the screen might have the pixel 
value of 7, which would match a color entry in the CLUT which 
has a pixel value of 7 and a RGB value of $000, $FFFF, $0000. 


O The Definitive MacTutor, Vol. 4 


This matching of the video buffer pixel values to the CLUT pixel 
values tells the card which colors to display on the screen. 

Now things suddenly change. The program decided that 
window one really wants to draw using a shade of Blue 
$0,$0,$FFFF. Тһе program uses SetEntryColor and Acti- 
vatePalette to change Red to Blue. In order for the Window to get 
this color, the Palette Manager needs to add a Blue entry to the 
CLUT (assume again there are no Blues in the current CLUT). 
The exact work of which colors stay and which change is 
dependent on Tolerances and other variables, but for this ex- 
ample, the Red $FFFF,$0,$0 entry in the CLUT is change to Blue 
$0,$0,$FFFF. Notice none of the Pixel values in the video buffer 
have changed. The RGB value of a certain entry in ће CLUT has 
changed, and nothing else. 

Back to the screen, while the user watches, everywhere were 
there was the Red shade $FFFF,$0,$0, there is now a Blue shade 
$0,$0,$FFFF. Through out the environment, all windows that 
showed that exact shade of Red, will show Blue. Red lips come 
out Blue, not exactly what the artist originally wanted. The video 
card can not change all the former Red pixel values in the video 
buffer; it has no idea what RGB colors each window wants to 
display. 

This is why when each Palette is connect to a window using 
SetPalette, there is a Update Boolean that needs to be passed. If 
cUpdate is true, the window will automatically be updated 
whenever the color environment changes. Then each window 
can redraw to the best color using the color environment. The 
flag should almost always be set to true. Again, this updating is 
completely transparent to the programmer; there is no code in the 
main program that causes updates whenever the color environ- 
ment is changed. 

Back at the windows, the top most window is updated. It 
draws using Blue. The lower three windows draw with the 
closest shade of Red, $CCCC,$0,$0. Now the second window is 
selected and becomes the top most window. The program does 
not change the Palettes, but because the top most window has 
changed, the color environment is about to. The new top most 
window has the highest priority when allocating entries in the 
CLUT, so Red $FFFF,$0,$0 is back on the table. The former top 
most window still gets it's Blue (due to the number of entries in 
the CLUT), sothe CLUT is changed. Againall the windows most 
be updated in order for them to show the best possible colors. 

The above model of changing the color environment is 
important to understand. The reader should have a feel for what 
happens when the color environment changes before going on. 


Palette Animation: Animating Colors 


Now think about what the Palette Manager did when it 
changed the color environment. It changed a few bytes of 
information in the CLUT. Because of this, no matter how many 
colors or where there were, those colors on the screen suddenly 
changed. To do the same thing using Copybits would be many 
factors slower. Accessing memory on Nubus cards is slower than 
normal memory. Even if access time was not slow, every pixel 
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with the old color must be changed. If large areas of the screen 
are that color, redrawing pixels is an extremely slow task. This 
is assuming that the program knew where all the pixels of a 
certain color were to begin with. Palette Animation simply 
consists of changing colors on the screen to create animation 
effect by manipulating the CLUT, and not the pixel values. 

In the above model, while colors do get changed, actual 
animation would be slow. Every time the environment changed, 
all the window are updated. Even if the animating window did 
not have it's CUpdate flag set, other windows оп the screen would 
need to be updated. It would be faster to use Copybits directly to 
create animation this way. Remember all Palette colors in the 
above model were Tolerant or Courteous Colors. All normal 
Palette use these types of colors, because when Tolerant and 
Courteous Colors are allocated on the CLUT, they can be used by 
other windows. 

There is another type of Color Entry: Animating Color. 
When these Colors are added to a CLUT, they are for exclusive 
use of the window/palette that allocated them. If a window was 
to be drawn using strictly animation colors, the colors of the 
entries in it's palette could be changed without effect the colors 
of the rest of the windows. Those other windows will never share 
animation colors with the animated window. 

Animating Colors are created the same way as Tolerant or 
Courteous colors. A Palette containing Animating Colors can be 
created with NewPalette or GetNewPalette, and attached to a 
window with SetPalette. Color Entries, which consist of RGB 
value, Usage value and Tolerance value, can be set with SetEn- 
tryColor and SetEntryUsage. Animating Colors have a usage of 
4, while the Tolerance is ignored. 

To draw with an Animating Color, PmForeColor and 
PmBackColor must be used. If RGBForeColor or 
RGBBackColor is used to set the Foreground or Background 
Color on an Animating Window, that color will NOT be drawn 
using Animating Colors. Instead it will use the best available 
color in the color environment. 

To change the animating Colors (and thus the screen colors) 
without changing the color environment, there are two special 
Palette Manager calls. AnimateEntry and AnimatePalette are 
designed to do this type of palette animation. Both calls are 
designed to work strictly with Animating Colors in a Palette. 
They change RGB values of certain entries of the Palette. The 
RGB values of entries in the CLUT of the video card will then be 
changed, causing the actual change of color on the screen. Since 
no other windows have the animating color, the color environ- 
ment is not considered to have changed, so no update events are 
posted. 

AnimateEntry is passed the animating window, the entry 
number of the Animating Color that will be changed, and the new 
RGB Color it will be changed to. AnimatePalette is passed the 
animating window, a Color Table (containing numerous RGB 
values), an Index value, Destination value and Length value. 
Beginning at the Index entry in the color table, a Length number 
of entries are copied to the Palette starting at the Destination 
entry. Thus, this call performs the same function as AnimateEn- 
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try, but for a group of animating colors. 
Special Effect: Moving Colors 


Now that the Palette Manager provides the capability of 
quickly changing the colors on the screen, how can a programmer 
use this to create animation effects? Consider what normal 
animation using normal Quickdraw requires. If a ball was 
suppose to be animated across the screen ata good speed, first the 
ball is drawn on on the screen. Then a certain length of time goes 
by toallow the user to see the ball. Next the ball is quickly erased, 
and redrawn at the new position. This may be repeated a number 
of times across the screen. To a viewer, it would look like the ball 
is being thrown across the screen. 

To do the same thing with Palette animation, a Palette is 
created with 3 entries and attached to a window. (One entry for 
the background, two for the two positions of the ball). The 
background will be green, while the ball will be white, so entries 
zero and two (entries are counted from 0 to М) will be set to RGB 
Green $0,$FFFF,$0, while entry one will be White 
$FFFF,$FFFF,$FFFF. 

Next the window is drawn (updated). The background is 
drawn to green, using PmBackColor, not RGBBackColor. The 
ballin the first position is drawn using entry one. The screen will 
show the white ballat this point. Next the second position of the 
ball is drawn using the third entry in the color table. Since that 
entry is set to green like the background, to the viewer, that ball 
is invisible. 


Fig. 2 Mixing colors 


Now theanimation starts. AnimateEntry is used to set entry 
one to green $0,$FFFF,$0 and entry two to white 
$FFFF,$FFFF,$FFFF. To the viewer, it looks like the ball has 
moved position. If there were more positions for the ball, there 
would be more entries (one for each new 
ball position). In that case, the animation 
routine would wait a certain amount of 
time so that the animation is not to fast 
for the viewer to see. Then ball is moved 
to the next position in the same manner 
(ie. entry two is set to green while entry 
three is set to white), and so on, and so 
on. 

Notice that it would take the same amount of time to animate 
the Ball using Palette Animation no matter how big the ball is. 
Using normal animation techniques, speed of animation usually 
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goes down for large objects. Also, the ball's position can be 
precalculated, something that may take too much time if done 
while animating. 

Animation Speed is important for all types of animation. If 
a ball is suppose to move across the screen at a set speed, two 
concepts effect this movement speed: distance between images 
of the ball and the speed at which these images can be changed 
(sometimes measured in images or frames per second). If the 
speed of animation is to slow, the distance between the ball must 
be increased. However, large distances between objects causes 
jerky animation, and is noticeable by viewer. If the speed of 
animation is very slow, the screen will actually be refreshed 
while quickdraw is drawing in the video buffer. This causes a 
ripple effect that is a characteristic of bad animation! It is better 
to have small movement and a higher animation speed. It might 
seem that the ball must be moved at least it's own size between 
each image or palette animation will not work. Not so... 


Special Effects: Overlaps 


Again examine what happens during normal animation of a 
ball across the screen. The ball is drawn in white on green. After 
a time, the ball is erased (ie. drawn in green) and redrawn at the 
new position. If the new position overlaps the old position, there 
will be pixels on the screen that were white at the beginning and 
are still white at the end of this operation. 

Therefore, the pixels in this example can be divided into four 
groups: those that always stay green, those that always stay 


white, those that start green, but change 
to white and those that start white, but 
change to green. Broken down that 
way, Palette Animation is simple. First 
a Palette is created with 4 Animating 
Color entries, the first and fourth are set 
to green, while the second and third are 
set to white. The background is drawn 
to green using the first animating color. 
The portion of the ball that is in the first position, but does not 
overlap the second is then drawnin white using the second color. 
The portion of the ball that is in the first position, and overlaps the 
second ball's position is then drawn in white using the third color. 
Finally the portion of the ball that is in the second position, but 
does not overlap the first is then drawn in green using the fourth 


Fig. 3 Ball Animation 


color. To the user, it would appear that there is only one ball in 
the first position. 

To animate, the second color, which was white, is set to 
green, whilethe fourth color which was green, is setto white. The 
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first and third colors would stay the same. For the user, it appears 
as if the ball has moved to the second position. 

This is the basis of Palette Animation. If the ball was 
expanded so that it's colors were Red, White and Blue, while the 
background was changed to show Green, Orange and Purple, the 
picture can still be broken down into groups of pixels that change 
from one color to another between two frames. First, determine 
the pixels that never change, then determine the pixels that 
change from one color to another. This concept can be expanded 
for more frames and/or more objects. In all cases, group the 
pixels into sets which change the same colors from one frame to 
another. 

The above techniques can be used for numerous effects. 
Many arcade games use these techniques along with normal 
animation. The twinkling of a rocket's jet or movement of an 
alien's fangs are both simple two step Palette Animation. This 
can be done separately while the rest of the game is being 
animated using traditional methods. It can be done no matter 
where the rocket is or how many aliens there are. Due to the low 
overhead in doing this type of animation, some graphic adventure 
games prefer simple animation using Palette animation. The 
twitching of an opponents eyes or the movement of an ocean 
wave are some common effects of such games. The effects are 
only limited by the programmer's imagination. 


Special.Effects: Rainbows and Fades 


Two other types of Special Effects using Palette Animation 
should be mentioned: Fades and Rainbows. An image drawn 
with Animating Colors can be easily Faded into some neutral 
Color. This is an attractive way to exit from an image (ie. similar 
to the way Movies dissolve from one scene to another). To do 
this, first a set number of intermediate steps is chosen to work 
with. Then a loop is cycled for that number of times. In that loop, 
each entry in the Palette is changed a constant amount so that 
when the entire loop is done, all the entries will have the same 
RGB value. For example, to fade to black in 256 cycles, during 
each cycle each entry's RGB values are reduced by 256th of the 
original value. То the viewer, all the colors will slowly fade to 
Black. Anentry which starts with the RGB value of $0,$FF00,$0 
would be reduced by $0,$00FF,$0, while an entry with a RGB 
value of $8000,$6700,$0 would be reduced by a value of 
$0080,$0067,$0 each cycle. Notice each Red, Green and Blue 
part of an RGB value is calculated separately. Also an image can 
fade to any RGB value, not just White, Black or even Gray. 

Опсе an image is faded out, a new image сап be faded in with 
the same technique. Assuming the second image uses the same 
Palette, it can be drawn while the screen is at the neutral color. 
Since the colors are still all the same, the new image will be 
invisible. Then it can be faded to either the old values, or even 
to any new values. The entries do not care at which point the 
program stops adjusting them. 

The other note-worthy effectis a Rainbow motion. A Palette 
is created which contains some spectrum of colors. While any 
arbitrary color set can be selected, in many cases, a Rainbow 
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spectrum is chosen. Once the Palette is create, some shape is 
drawn so that the full range of entries are used. Different shapes 
include parallel lines, arcs in a circle, circles within each other or 
even lines in a web pattern. Then the Palette is animated so that 
every entry's RGB value is moved to the next entry (and the last 
one is moved to the front of the list). The resulting animated 
motion can be hypnotizing. 


PalFun: A Dynamic Colorful Example 


PalFun, this months sample program, demonstrates some of 
the techniques described this month, as well as some of the 
concepts discussed last issue. The reader can for the most part 
ignore the main portion of the program (an exceptionally simple 
program) once he understands that this is a shell designed to 
create, display and animate Palette windows. In PalFun, every 
window has a routine associated with it that creates the Window/ 
Palette (MakeSomeWindow), a routine associated that updates 
the image (UpdateSomeWindow) and some have a routine asso- 
ciated that animates the image (AnimateSomeWindow). 

Red Window, Green Window and Blue Window demon- 
strate various ways to create normal Palettes. Try picking 
different windows, and notice how this effects the current color 
environment. Also, notice how each window is automatically 
updated. Change the bit depth of the Video Card (ie. number of 
bits per pixel) and see how the Windows change. Notice that the 
Blue window uses a method of Color Priority (mentioned last 
month) that allows it to appear at it's best no matter what Pixel 
or Window depth. 

Current Color Window uses Explicit Colors (explained last 
month). Explicit colors provide a convenient way for the user to 
view the current color environment. An Explicit entry is not 
drawn using it’s RGB value. Instead it displays the CLUT'scolor 
at it's corresponding position. For example, the fifth entry in 
Palette will display the fifth entry in the CLUT of the video card. 
Explicit colors is the only method to view Animating Colors in 
some window other than the one the Animating Colors were 
created for. When selecting various windows and/or running 
through Animation techniques, keep an eye on the Current Color 
Window to view what's happening. Converting Current Color 
into a Desk Accessory creates a useful tool for anyone who 
tinkers with the Palettes. 

Ball Window gives the basic example of moving a non- 
overlapping ball around a screen. Shapes demonstrates how to 
calculate the overlaps and pixels of different, completely arbi- 
trary 2-bit images in order to step through the images. It uses 
unions and intersections of regions in order to find out what 
pixels change into what colors. For example, given three regions 
(images), the pixels that will never change colors are the ones that 
do not intersect the 3 regions, or there intersections between А 
region, B region and C region. The pixels that would be set 
(Black) for the first image, then clear (White) for the next 2 
images are the pixels that in А Region minus the ones that are in 
B and C regions. Notice that if the result of any such calculation 
is the empty region, there is no pixels of thatcolor and that pixel's 
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Color Entry really does not have to be allocated/used. Fade and 
Rainbow are the last two windows. They demonstrate the above 
mentioned Fade and Rainbow techniques. 


Last Comments: Palette Techniques 
Here are some last comments for this month: 


е Always start a Palette with a White and Black color entry. 
Due to a bug in the Palette Manager, the first entry must 
be White or Black. Even without this, it is good practice 
to always have White and Black as the first two colors in 
a Palette (remember Color Priorities?). 


е Animating Windows should still have the cUpdates flag 
set when SetPalette is called. This will prevent undesired 
animation when ActivatePalette reserves entries that were 
being used by the animating window. 


When using the Palette Manager, the user may sometimes 
see the Background Desktop pattern change colors when 
the windows are dragged around. This happens most 
often when the Colors used in the Background Pattern (set 
by the Control Panel) are something other than Black and 
White. What has occurred is that the Palette Manager has 
changed the Color Environment, but the Window Man- 
ager (which takes care of the Background) does not 
known this. This is due to a problem with the Window 
Manager that will hopefully be fixed. 


While Shape demonstrates how to calculate animating 
arbitrary images, it is best to design the image with 
Palette animation in mind. Keep the colors in separate 
portions of the screen, so they do not intersect too many 
times and need separate entries. The lower the number of 
sets of pixels, the more images that can be animated. A 
good Palette Manager example would be a program that 
takes arbitrary MacPaint documents and displays them 
one after another using Palette Animation. The Applica- 
tion could be smart enough to keep track of Pixel differ- 
ences (ie. unions and intersects of bitmaps) so that it 
keeps track of the maximum number of entries that need 
to be used. The Application could keep adding MacPaint 
pictures until the maximum number of entries of the 
Video Card is reached, and then quickly flash through the 
pictures. 


When should a programmer use SetPalette vs using a 
*pltt' resource? This is the same as asking when a 
programmer should use New Window vs using a ‘WIND’ 
resource; it depends on when the settings of the Window 
or Palette are calculated. If they are calculated at run time 
or constantly changing during the development of the 
program, use SetPalette. This provides the most flexibil- 
ity to the programmer. If the Palette is precalculated (ie. 
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always the same for every run of the program), use the 
“ріш” resource to separate the Color from the Code. This 
is done for the same reason most programmers separate 
the Text from the Code: Localization. 


е A Special Thank you to Art Cabral for the help he 
provided in understand the Palette Manager (No more 2 
minute long phone calls, Art). 


Next issue, manipulating Color Icons and a Color Icon 
Editor. Even if there are tools to do this by then, the understand- 
ing of advance Color Quickdraw data structures is worth the 
study. 


About the Program Code 


PalFun is written in MPW Pascal, available on the MacTutor 
Source Code disk for this issue. The listing here has been 
translated into LS Pascal (and should work as is in Turbo Pascal 
also) by the Editor. The resources are also listed here in RMaker 
format, but the Rez format is on the Source Code Disk. The MPW 
version is a single program, but for LS Pascal, the program had 
to be broken into this main program, and two units: one unit for 
the globals and the other unit for all the Palette specific routines 
called PalFunStuff. Since LS Pascal is the most generic of all the 
Pascal compilers, this listing should be most easily entered into 
all the other compilers, MPW, Turbo and TML by just changing 
the USES statement. 


{ PalFun by Steve Sheets 3/88 ) 
(Palette Manager Sample Progrem designed for MacTutor.) 
(It demonstrete various Palette Animation effects.) 


PROGRAM PalFun; 


USES 
К0М85, ColorQuickDrew, ColorWindowMgr, PaletteMgr, 
PickerIntf, PalFunGlobals, PalFunStuff; 


(хазжхжзяж Main Portion Programs ®®%®*®**®*®хххх} 
PROCEDURE crash; 
BEGIN 


ExitToShel1; 
END; 


PROCEDURE SetUp; 
VAR 


count : integer; 
BEGIN (Standard Mac Program setup) 
InitGraf CéthePort); 
InitFonts; 
FlushEventsCeveryEvent, 0); 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogsCGcresh); 
InitCursor; 


FOR count := appleM TO menuCount DO 

nyMenus[count] := GetMenuCcount); 
AddResMenu(CmnyMenus [appleM], “DRVR/); 
FOR count := eppleM TO menuCount DO 
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BEGIN 

moveHH i ChandleCmyMenus [count 122; 

қылышы 

FOR count := арр1еМ TO menuCount DO 
ІпѕегМепиСтуМепиѕ [count], 0); 

DrawMenuBar ; 


WITH screenBits.bounds DO 
SetRect(dragRect, 4, 24, right - 4, bottom - 4); 
doneFlag := FALSE; 


FOR count := 1 ТО numWindows DO 
BEGIN 
MyWindow[count] := NIL; 
MgPalette[count] := NIL; 
END; 
END; 


(Given a Window ID number, close Window/Palette) 
PROCEDURE CloseIt (N : INTEGER); 
BEGIN 
IF (М > Ø) AND (N <= numWindows) THEN 
BEGIN 
IF MyPalette[N] © NIL THEN 
DisposePalette(MyPalette[N1); 
MyPalette[N] := NIL; 
IF MyWindow[IN] € NIL THEN 
DisposeWindowC(MyWindow [№] >; 
MyWindowIN] := NIL; 
END; 
END; 


(Gets the Front most Window ID number.) 
FUNCTION GetWindowNum (W : WindowPtr) : INTEGER; 
VAR 


N, count : INTEGER; 
BEGIN 
IF W = NIL THEN 
GetWindowNum := 0 


ELSE 
BEGIN 
М := Ø; 
FOR count := 1 ТО numWindows DO 
IF MyWindow[count] = W THEN 
М := count; 
GetWindowNum := М; 
END; 
END; 


( Standard Handling of the Menu. Selecting the Window Menu, 
bring that window to the front and that’s all (Palette Manager 
handles changing colors and creating update). Animate Menu 
animate the front window if it can. } 
PROCEDURE DoCommand (mResult : LONGINT); 
VAR 


theltem : INTEGER; 
theMenu : INTEGER; 
name : 517255; 
N : INTEGER; 
dummy : Boolean; 
tempPort : GrafPtr; 
BEGIN 
theItem := LoWord(mResu1t); 
theMenu := HiWord(mResult); 
CASE theMenu OF 
eppleM : 
IF theItem - 1 THEN 
theItem := AlertCAlertID, NIL) 
ELSE 
BEGIN 
GetItem(nyMenus[appleM], theItem, name); 
М := OpenDeskAcc(name); 
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END; 
fileM : 
CASE theItem OF 
1 . 


ВЕСІН 
GetPort(tempPort); 
SetPort(FrontWindow); 
CASE GetWindowNum(FrontWindow) ОР 
ballW : 
AnimBall; 
shapeW : 
AnimShape; 
r&inbowW : 
AnimRainbow; 
fadeW : 
AnimFade; 
OTHERWISE 
END; 
SetPortCtempPort); 
END; 


 CloseIt(GetWindowNumCFrontWindow2; 


doneFlag := TRUE; 
OTHERWISE 
7 
editM : 
dummy := SystemEditCtheItem - 1); 
winM : 
IF CtheItem > Ø) AND CtheItem <= numWindows) 


BEGIN 

IF MyWindowLtheItem] = NIL THEN 
BEGIN 

CASE theItem OF 
redW : 

МакеКед; 

greenW : 
MakeGreen; 

blueW 


THEN 


shapeW : 
MekeShepe; 

rainbowW : 
MakeRainbow; 

fadeW : 
MakeFade; 

OTHERWISE 

END; 
END 


SE 
SelectWindowC(MyWindow[theItem1); 
END; 
OTHERWISE 


END; 
HiliteMenu(@); 
END; 


(Extremely Standard Main Program Loop.) 
PROCEDURE DoMainLoop; 
VAR 
theChar : CHAR; 
myEvent : EventRecord; 
whichWindow : WindowPtr; 
oldPort : GrafPtr; 
dummy : boolean; 
BEGIN 
REPEAT 
SystemTask; 
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IF GetNextEventCeveryEvent, myEvent) THEN 
CASE myEvent . what OF 
mouseDown : 
CASE FindWindow(myEvent where, whichWindow) ОҒ 
inSysWindow : 
SystemClickC(mnyEvent, whichWindow); 
inMenuBar : 
DoCommandCMenuSelect(myEvent .мНеге)); 
inGoAway : 
IF TrackGoAwayCwhichWindow, myEvent where?) 
THEN 
CloseItCGetWindowNumCwhichWindow2); 
inDreg : 
IF (FrontWindow € whichWindow) THEN 
SelectWindow(whichWindow) 
ELSE 
DregWindow(whichWindow, myEvent.where, 
dragRect); 
inContent : 
IF (FrontWindow © whichWindow) THEN 
SelectWindow(whichWindow); 
OTHERWISE 
END; (of mouseDown) 
keyDown, autoKey : 


theChar := CHR(BitAnd(myEvent . message, 
charCodeMask 2); 

IF BitAnd(nyEvent.modifiers, cmdKey) © Ø 
THEN 


DoCommand(MenuKey( theChar 22; 
END; 
updateEvt : 
BEGIN 
whichWindow := WindowPtr(myEvent .message 2; 
IF whichWindow © NIL THEN 


GetPortColdPort); 
SetPor tCwhichWindow); 
BeginUpdateCwhichWindow); 
CASE GetWindowNumCwhichWindow) OF 
redW : 
DoRedUpdeate; 
greenW : 
DoGreenUpdate; 
blueW : 
DoBlueUpdate; 
curW : 
DoCurUpdate; 
ballW : 
DoBallUpdate; 
shapewW : 
DoShapeUpdate ; 
rainbow : 
DoRainbowUpdate; 
fadeW : 
DoFadeUpdate; 
OTHERWISE 
END; 
EndUpdateCwhichWindow); 
SetPortColdPort); 
END; 
END; 
OTHERWISE 
END; 
UNTIL doneF lag; 
END; 


(Dispose of all the Palettes and closes all the Windows.) 
PROCEDURE CloseDown; 
VAR 
count : integer; 
BEGIN 
FOR count := 1 ТО numWindows 00 
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CloseltCcount); 
FOR count := appleM TO menuCount DO 
BEGIN 
De leteMenuCcount ); 
DisposeMenuCmyMenus [count 12; 
END; 
DrawMenuBar ; 
END; 


( Main Body Program. 


BEGIN 
IF ColorQDExists THEN 
BEGIN 
SetUp; 
DoMainLoop; 
CloseDown; 
END; 
END. 


Setup, Do it, Close down.) 


UNIT PalFunStuff ; 
INTERFACE 


USES 
К0М85, ColorQuickDraw, ColorWindowMgr, PaletteMgr, 
PickerIntf, PalFunGlobals; 


FUNCTION ColorQDExists : 


PROCEDURE AnimBall; 
PROCEDURE AnimShape; 
PROCEDURE AnimRainbow; 
PROCEDURE AnimFade; 


PROCEDURE МакеКед; 
PROCEDURE MakeGreen; 
PROCEDURE MakeBlue; 
PROCEDURE МакеВа11; 
PROCEDURE MakeCur ; 
PROCEDURE MakeShepe; 
PROCEDURE MakeRainbow; 
PROCEDURE MakeFade; 


PROCEDURE DoRedUpdate; 
PROCEDURE DoGreenUpdate; 
PROCEDURE DoBlueUpdate; 
PROCEDURE DoCurUpdate; 
PROCEDURE DoBal Update; 
PROCEDURE DoShapeUpdate; 
PROCEDURE DoRainbowUpdate; 
PROCEDURE DoFadeUpdate; 


IMPLEMENTATION 


boolean; 


(xxxxxxiixxxxxxXEiXkk General Tools XXXxxxziricoooooeeeep) 


(Returns true if the Мас had Color Quickdraw. } 
FUNCTION ColorQDExists; (boolean) 
CONST 
ROM85Loc = $28E; 
TwoHighMask = $C000; 
TYPE 
WordPtr - ^INTEGER; 
VAR 
Wd : WordPtr; 
BEGIN 


Wd :- POINTERCROM85Loc); 


ColorQDExists := (BitAnd(CWd^, TwoHighMask) = 0); 
END; 
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(Stuffs Red, Green & Blue into RGBColor} 
PROCEDURE SetRGB (VAR RGB : RGBColor; 
R, G, В: INTEGER); 
BEGIN 


RGB.Red := R; 
RGB.Green := 6; 
RGB.Blue := В; 
END; 


(Copies RGBColor into RGBColor) 
PROCEDURE CopyRGB (RGBsrc : RGBColor; 
VAR RGBdest : RGBColor); 
BEGIN 


RGBdest.Red := RGBsrc.Red; 
RGBdest.Green := RGBsrc.Green; 
RGBdest .Blue := RGBsrc.Blue; 
END; 


(Delays a set length time. usually until) 
( the screen in refreshed (prevents ripples)) 


PROCEDURE DoDelay (N : INTEGER); 
VAR 
L : LONGINT; 
BEGIN 


L := TickCount + М; 
WHILE L » TickCount DO 


4 


END; 


{Using 16 Bit Unsigned Integers: C:=A/B) 
PROCEDURE UnSignedDiv (А, B : INTEGER; 
VAR С : INTEGER); 


VAR 
L : LongInt; 
BEGIN 
IF A < 0 THEN 
L := А + 65536 
ELS 
L :=А; 
С := LoWordCL DIV В); 
END; 


(Using 16 Bit Unsigned Integers: А:=А+В} 
PROCEDURE UnSignedAdd (VAR А : INTEGER; 
B : INTEGER); 


VAR 
L : LongInt; 
BEGIN 
IF А < Ø THEN 
L := А + 65536 + B 
ELSE 
L := À +B; 
А := LoWord(L); 
END; 


(Using 16 Bit Unsigned Integers: A:=A-B) 
PROCEDURE UnSignedSub (VAR А : INTEGER; 
B : INTEGER); 
VAR 


L : LongInt; 
BEGI 


N 
IF А < 0 THEN 
L := А + 65536 - B 


ELSE 
L := А-В; 
A := integer(LoWord(L)); 
END; 


(жжжжжхжжхкжжкжкккжхжя Color Table Tools XXXtxxibrópnoopebonero) 


(Given number of Colors to be placed in it, creates а blank 
CLUT. Cives it) 
( ап unique Seed апа correct value, but no colors.) 
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FUNCTION NewCT (№ : integer) : CTabHandle; 
VAR 


MyCT : MyCTabHandle; 
count : integer; 


MyCT := NIL; 
IF (М > Ø) AND (N <= MaxCT) THEN 
BEGIN 
МУСТ := POINTERCNewHandleCCN * SIZEOFCColorSpec)) 
+ (2 ж SIZEOFCinteger)) + SIZEOFClongint))); 
IF MyCT o NIL THEN 
WITH MyCT^^ DO 


BEGIN 
ctSeed := GetCTSeed; 
ctFlag := 0; 
ctSize := N - 1 


ы д 
FOR count := TON - 100 
WITH ctTeble(count] DO 
BEGIN 
value := count; 
SetRGB(rgb, 0, 0, 0); 
ND; 


д 


END; 
D; 


NewCT := POINTERCMYCT); 
END; 


(Stuffs ап RGB value in the Nth Color (numbered 0 to N) of the 
L 


Ts 
PROCEDURE SetCTEntry (С : CTabHandle; 
N, R, 6, B : INTEGER); 
VAR 


MyCT : MyCTabHandle; 
BEGIN 
МУСТ := POINTERCC; 
SetRGBCMyCT^^ .ctTeble(n].rgb, В, G, В); 
END; 


(*xxkkkkxxkkkxkkiikikk Red EXEKKSKKKKERAKASELES ) 


(Red Window displays encompassing red-shaded circles.) 
(This creates а 3-0 Globe effect.) 


(Create Red Window/Palette with NewPalette & SetEntryColor 
commands. } 
PROCEDURE MakeRed; 
VAR 
tempRect : rect; 
tempRGB : RGBColor; 
$ : str255; 
count : integer; 
BEGIN 
SetRect(tempRect, 20, 40, 320, 340); 
GetIndString(S, StrID, 1); 
MyWindowI[redW] := NewCWindowCNIL, tempRect, S, true, 
noGrowDocProc, POINTER(-1), true, 0); 


MyPalette[redW) := NewPaletteC128, NIL, pmTolerant, 0); 
SetRGBCtempRGB, ColorStert, 0, 0); 
FOR count := 0 TO 127 DO 
BEGIN 
SetEntryColor(MyPalette[redW], count, tempRGB); 
UnSignedSub( tempRGB.red, ColorInc); 
END; 


SetPaletteCMyWindow[redW), MyPalette[redW], true); 
END; 


(Draw the Red Window using RGBForeColor.) 
PROCEDURE DoRedUpdate; 
VAR 
tempRect : rect; 
tempRGB : RGBColor; 
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count : integer; 

BEGIN 
SetRectCtempRect, 22, 22, 278, 278); 
SetRGBCtempRGB, ColorStart, 0, 0); 


FOR count := 0 TO 127 DO 
BEGIN 


RGBForeColor( tempRGB); 
PaintOval(tempRect); 
InsetRectCtempRect, 1, 1); 
UnSignedSub( tempRGB . red, ColorInc); 
END; 
END; 


(ХЖЖЖЖЖЖЖАЖЖЕЖЖЖЖЖЕКХ бгееп XX*XXXXxrxx*tkxrxkxrkxx) 
(Green Window displays a Green Globe.) 


(Create Green Window/Palette with NewPalette command & CLUT 
procedures.) 
iie ro MakeGreen; 
VAR 
tempRect : rect; 
tempRGB : RGBColor; 
tempCT : CTabHandle; 
Col : INTEGER; 
$ : str255; 
count : integer; 
BEGIN 
SetRectCtempRect, 40, 60, 340, 360); 
GetIndString(S, StrID, 2); 
MyWindow[greenW] :- NewCWindowCNIL, tempRect, S, true, 
noGrowDocProc, РОІМТЕВС- 1), true, 0); 


tempCT := МенСТ( 128); 
Col := ColorStert; 
FOR count := 0 TO 127 00 
BEGIN 
SetCTEntryCtempCT, count, 9, Col, 0) 
UnSignedSubCCol, ColorInc); 
END; 
к MyPalette[greenW] := NewPaletteC128, tempCT, pmTolerant, 
DisposHandleCHandleCtempCT)); 


SetPeletteCMyWindowlgreenW], 
END; 


MyPelette[greenW], true); 


(Drew the Green Window using PmForeColor.) 
PROCEDURE DoGreenUpdate; 
VAR 
tempRect : rect; 
count : integer; 
BEGIN 
SetRectCtempRect, 22, 22, 278, 218); 
FOR count := 0 TO 127 00 
BEGIN 
PmF oreColor(count); 
PeintOvalCtempRect); 
InsetRect(tempRect, 
END; 
END; 


(*22x25 355535 55XXXXXXX5 Blue X3XXXXXXX1XX1X5X5XXXX) 


1, 1); 


ак: а Blue Globe (like Green Window), but now the colors 
(are set up for better displaying Cie. Color Priority2.) 


(Create Green Window/Palette with NewPalette command & CLUT 
procedures.) 


PROCEDURE MakeBlue; 
VAR 
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tempRect : rect; 

tempRGB : RGBColor; 

tempCT : CTabHandle; 

Col INTEGER: 

9: 34-255, 

h, v : integer; 

BEGIN 
SetRect(tempRect, 60, 80, 360, 380); 
GetIndString(S, StrID, 3); 
MgWindow[blueW] := NewCWindow(NIL, tempRect, S, true, 
noGrowDocProc, POINTER(-1), true, 0); 


tempCT := NewCT( 128); 
Col := ColorStart; 
FOR h := 0 TO 15 DO 
FOR v := 0 TO 7 DO 
BEGIN 
SetCTEntryCtempCT, (у * 16) + h, В, 0, Col); 
UnSignedSub(Col, Colorinc); 
MyPalette[bluew ] :* NewPaletteC128, tempCT, pmTolerant, 
0); 
DisposHandleCHandle(tempCT )); 


SetPaletteCMyWindow[blueW), 
END; 


MyPalette[blueW], true); 


(Draw the Blue Window using RGBForeColor. } 
PROCEDURE DoBlueUpdate; 


VAR 
tempRect : rect; 
tempRGB : RGBColor; 
count : integer; 
BEGIN 


SetRect(tempRect, 22, 22, 278, 278); 
SetROBCtempRGB, 0, 0, ColorStart); 
FOR count := 0 Т0 127 00 

BEGIN 


RGBForeColor(CtempRGB); 
PaintOvalCtempRect); 
InsetRectCtempRect, 1, 10; 
UnSignedSub( tempRGB.Blue, ColorInc); 
END; 
END; 


(ххххххха ххх ххх Current Color XXXXXXXkXxtxrxrtrxxxx) 
(Displays the Current Color Enviroment) 
(Create the current Color Window using Explicit colors ) 


(Сбоев not have to set the colors).) 
PROCEDURE MakeCur ; 


VAR 
tempRect : rect; 
$ : str255; 
BEGIN 
SetRectCtempRect, 100, 80, 420, 400); 
GetIndString(S, StrID, 4); 
MyWindowtcurW] := NewCWindowC(NIL, tempRect, S, true, 
noGrowDocProc, POINTERC- D, true, 0); 
MyPalette[curW] := NewPalette(256, NIL, pmExplicit, 0); 
SsetPaletteCMyWindow(curw], MyPalettefcurW], true); 
END; 


(Draws the current Graphic Device Colors.) 
PROCEDURE DoCurUpdate; 
VAR 
X, у, n : integer; 
tempRect : rect; 


ВЕСІ 
n := 0; 
FOR y - 0 TO 15 DO 
FOR x := 0 TO 15 DO 
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BEGIN 
PmForeColor(n); 
SetRect(tempRect, x * 20, u * 20, (x + 1) х 
20, (y + 1) * 20); 


PaintRectCtempRect); 
n :=n+ 1; 
END; 


END; 


(ooeeceooocoooeoeeeeer Ball ЖЖ ЖЖ ХЕ ЖЖ ee xk) 


(Sinple Palette Animation of а Ball Across the Screen) 


(Create the Ball Animation Window using Animated colors.) 
PROCEDURE МәкеВа11; 
VAR 
tempRect : rect; 
tempRGB : RGBColor; 
S : str255; 
count : integer; 
BEGIN 
SetRectCtempRect, 100, 120, 400, 420); 
GetIndString(S, StrID, 5); | 
MyWindow[ballW] := NewCWindowCNIL, tempRect, S, true, 
noGrowDocProc, POINTER(-1), true, 0); 


MyPelette[ballW] := NewPaletteC19, NIL, pmAnimated, 0); 


SetRGBCtempRGB, $FFFF, $FFFF, $FFFF); 
SetEntryColor(MyPalette([bal1W], Ø, tempRGB); 
SetRGBCtempRGB, 0, 0, 0); 
SetEntryColor(MyPalette[ballW], 1, tempRGB); 
tempRGB.blue := $FFFF; 
SetEntryColor(MyPalette[ballW], 2, tempRGB); 
tempRGB.blue := Ø; 
tempRGB.red := $FFFF; 
FOR count := 3 TO 18 DO 
SetEntryColor(MgPalette[ballW], count, tempRGB); 
SetPaletteCMyWindow[ballW], MyPalette[ballW], true); 
END; 


(Draw the Balls in the window using PmForeColor.) 
PROCEDURE DoBal Update; 
VAR 


R : rect; 
count : integer; 
BEGIN 
SetRect(R, 0, 0, 10000, 10000); 
РигогеСо10г( 18); 
PaintRect(R); 


FOR count := 2 TO 17 DO 
BEGIN 


R.top := 16 * count; 
R.left := R.top; 
R.bottom := R.top + 16; 
R.right := R.bottom; 
PmForeColor (count); 
PaintOval(R); 

END; 
END; 


(Animate the Ball through the window using AnimateEntry. } 
PROCEDURE AnimBa11; 
VAR 
R, В: RGBcolor; 
time, count, temp : integer; 
BEGIN 


SetRGB(R, $FFFF, 0, Ø); 
SetRGB(B, Ø, Ø, $FFFF); 


FOR tine := 1TO 10 DO 
РОК count := 2 TO 17 00 
BEGIN 


IF count = 17 THEN 
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temp := 2 
ELSE 

temp := count + 1; 
DoDelay( 1); 


AnimateEntryCMyWindow[ballW], count, R); 
AnimateEntryCMyWindow[ballW], temp, В); 
END; 
END; 


(ЖЖЖЖЖЖЖХЖ ЖЖ ЖЖ Shepe хакко) 


( Given 3 arbitrary regions (Black/White images), calculates 
how to draw the window so that the images can be shuffled 
through quickly. } 


(Create the Shape Animation Window) 
((^pltt^ is automatically loaded іп).) 
PROCEDURE MakeShape; 
BEGIN 
MyWindow[shapeW) 
POINTERC- 125; 
END; 


:= GetNewCWindow(ShapeID, NIL, 


(Draws Shape. aRgn,bRgn,cRgn are the arbitrary images.) 
PROCEDURE DoShapeUpdate; 
VAR 


eRgn, bRgn, cRgn, TempRgn : RgnHandle; 

count : INTEGER; 

TempRect : Rect; 
PROCEDURE ОгамТг1ад Ch, у: 
BEGIN 

MoveTo(h + 25, м); 

Line(-25, 50); 

Line(58, 0); 

Line(-25, -50); 


END; 
BEGIN 
aRgn := NewRgn; 
OpenRgn; 
SetRectCtempRect, 10, 10, 60, 60); 
FremeüvalCtempRect); 
SetRectCtempRect, 120, 
FrameRect(tempRect); 
SetRectCtempRect, 120, 80, 170, 130); 
FrameRect(tempRect); 
SetRect(tempRect, 190, 
FrameRect(tempRect); 
SetRect(tempRect, 190, 80, 240, 130); 
FrameRect(tempRect); 
SetRect(tempRect, 10, 80, 110, 81); 
FOR count := 1 TO 25 DO 
ВЕСІН 
FrameRect(tempRect); 
OffSetRectCtempRect, 0, 2); 
END; 
CloseRgnCaRgn); 
bRgn := NewRgn; 
OpenRgn; 
SetRectCtempRect, 35, 10, 85, 605; 
FremeOvalCtempRect?); 
SetRect(tempRect, 120, 10, 
FrameOvalCtempRect); 
SetRect(tempRect, 120, 80, 
FraemeüvalCtempRect); 
SetRect(tempRect, 190, 10, 240, 60); 
FrameOvalCtempRect); 
SetRect(tempRect, 190, 80, 240, 130); 
FrameOval(tempRect); 
SetRectCtempRect, 10, 80, 11, 130); 
FOR count := 1 Т025 DO 
BEGIN 
FrameRectCtempRect 2; 
OffSetRectCtempRect, 4, 0); 


INTEGER); 


10, 170, 60); 


10, 240, 60); 


170, 60); 
170, 130); 
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END; 
CloseRgnCbRgn); 
cRgn := NewRgn; 
OpenRgn; 
SetRectCtempRect, 60, 10, 110, 60); 
FremeOvalCtempRect); 
DrewTriagC120, 10); 
DrawTriag( 120, 80); 
DrawTriag(198, 10); 
DrewTriagC190, 80); 
МоуеТ0(60, 80); 
Line(58, 25); 
Line(-50, 25); 
Line(-50, -25); 
Line(50, -25); 
CloseRgnCcRgn); 
TempRgn :- NewRgn; 


(This Region will always be Red (Background)) 
РаҒогеСо10г(0); 
SetRect(tempRect, -32000, -32000, 32000, 32000); 
PaintRectCtempRect?; 


(This region will start Blue, chenge Red, stay Red) 
PmForeColor( 1); 
DiffRgnCeRgn, bRgn, TempRgn); 
DiffRgnCTempRgn, cRgn, TempRgn); 
PaintRgnCTempRgn); 


(This region will be Red,Blue,Red) 
PnForeColor(2); 
DiffRgnCbRgn, eRgn, TempRgn); 
DiffRgnCTempRgn, cRgn, TempRgn); 
PaintRgnCTempRgn); 


(This region will be Blue,Blue,Red) 
PnForeColor(3); 
SectRgn(aRgn, bRgn, TempRgn); 
PaintRgn(TempRgn); 


(This region will be Вед, еа, Blue} 
PmForeColor (4); 
DiffRgnCcRgn, eRgn, TempRgn); 
DiffRgnCTempRgn, bRgn, TempRgn); 
PaintRgnCTempRgn?; 


(This region will be Blue,Red, Blue} 
PmForeColor(5); 
SectRgnCeRgn, cRgn, TempRgn); 
PaintRgnCTempRgn); 


(This region will be Red,Blue,Blue} 
PmForeColor (6); 
SectRgn(bRgn, cRgn, TempRgn); 
PaintRgn(TempRgn ); 


(This Region will always be Blue} 
PmForeColor(7); 
SectRgnCeRgn, bRgn, TempRgn); 
SectRgnCcRgn, TempRgn, TempRgn); 
PaintRgnCTempRgn); 


DisposeRgnCaRgn); 
DisposeRgn(bRgn); 
DisposeRgnCcRgn); 
DisposeRgn(TempRgn ); 
END; 


(Animate the Shape image using AnimatePalette/CLUT resouces. } 


PROCEDURE AnimShape; 
VAR 
count : INTEGER; 
MyCLUT : ARRAY[1..3] OF CTabHandle; 
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BEGIN 
FOR count := 1 TO 3 DO 
MyCLUT [count] := GetCTableCcount + 300); 


DoDelay( 1); 

AnimatePaletteCMyWindow[shapeW), MyCLUT([2], 0, 
DoDe lay(68); 

AnimatePaletteCMyWindow[shapeW1, MyCLUT([3], Ø, 
DoDelay(690); 

AnimatePaletteCMyWindow[shapeW], MyCLUT(11, Ø 
DoDelau(50); 


FOR count := 1 TO 5 DO 

BEGIN 

DoDelau( 10); 

AnimatePaletteCMyWindow[shapeW], MyCLUTI2], 
8); 

DoDelay( 12); 

AninatePaletteCMyWindow[shapeW], MyCLUT(3], 
8); 
DoDelay( 10); 
AnimatePaletteCMyWindow[shapeW], MyCLUT(1), 


END; 
DoDe lay(68); 


8); 


FOR count := 1 TO 5 DO 

BEGIN 

DoDelayC1); 

AnimatePaletteCMyWindow[shapeW], MyCLUT(2), 
8); 

DoDelay( 1); 

AnimatePaletteCMyWindow[shapeW], MyCLUT(3], 
8); 

DoDelau(1); 

AnimatePalette(MuWindow[shapeW], MyCLUTI 1], 


END; 


FOR count := 1 TO 3 00 
DisposCTableCMgCLUT (count 1); 
END; 


8); 


(foe ха ххх eek Rainbow X*X*XXtXrtkXrxtktXtkxk) 


(Demonstrates the Rainbow Effect (Rotating Circle,) 
vas Bands and Expanding Circle).) 


((Create the Rainbow Animation Window.) 
E i MakeRainbow; 
AR 


tempRect : rect; 
tempRGB : RGBColor; 
S : str255; 

tempHSV : HSVColor; 
count : integer; 

BEGIN Ç 
SetRect(tempRect, 50, 160, 590, 400); 
GetIndString(S, StrID, 6); 
MyWindow[rainbowW] 

noGrowDocProc, POINTERC-1), true, 0); 


8); 
8); 


:= NewCWindow(NIL, tempRect, S, true, 


MyPalette[rainbowW] := NewPaletteC122, NIL, pmAnimated, 


0); 


SetRGBCtempRGB, $FFFF, $FFFF, $FFFF); 
SetEntryColor(MyPalettel[rainbowW)], Ø, tempRGB); 
SetRGBCtempRGB, 0, 0, 0); 
SetEntryColor(MyPelette[rainbowW], 1, tempRGB); 
tempHSV.saturation := $FFFF; 
tempHSV.value := $FFFF; 
FOR count := 1 TO 129 DO 

BEGIN 
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tempHSV.hue := ($ØFFFF * count) DIV 120; 

HSV2RGBCtempHSV, tempRGB); 

SetEntryColor(MyPalettel[rainbowW], count + 1, 
tempRGB); 


SetPalette(MguWindow[rainbowW], MyPalette[rainbowW], 
true); 
END; 


(Draws the raus of the Rainbow.) 
PROCEDURE DoRainbowUpdate; 
VAR 
count : INTEGER; 
tempRect, CRect : Rect; 
BEGIN 
SetRectCtempRect, Ø, Ø, 480, 240); 
PmForeColor(@); 
PaintRectCtempRect); 
SetRectCtempRect, 0, 0, 240, 240); 
SetRectCCRect, 300, Ø, 540, 240); 
FOR count := 0 TO 119 DO 
BEGIN 
PmForeColor(count + 2); 
PaintArcCtempRect, count * 3, 3); 


МоуеТ0(240, count); 

[ іле(60, 0); 

МоуеТо(240, count + 120); 
LineC60, 0); 


PaintOval(CRect); 
InsetRect(CRect, 1, 1); 
END; 
END; 


(Rotates all the entries in the CLUT one position. } 
PROCEDURE BumpCTEntry (С : CTabHandle); 
VAR 


tempRGB : RGBcolor; 
MyCT : MyCTabHandle; 
count : INTEGER; 
BEGIN 
MyCT := POINTERCC); 
WITH MyCT^* DO 


EGIN 
CopyR6BCctTable[2].rgb, tempRGB); 


FOR count := 1 TO ctSize DO 
CopyRGBCctTable[count].rgb, ctTable[count - 
1J.rgb); 


CopuRGB(tempRGB, ctTable[ctSize].rgb); 
D: 


7 


END; 


(Animate the Rainbow using AnimatePalette. This one) 
(creates and manilpulates it’s CLUT directly.) 
PROCEDURE AnimRainbow; 
VAR 
count : INTEGER; 
tempRGB : RGBColor; 
tempCT : CTabHandle; 
BEGIN 
tempCT := NewCTC 120); 
FOR count := 1 TO 120 DO 
BEGIN 
GetEntryColor(MyPalettelrainbowW], count + 1, 
‚ tempRGB); 
SetCTEntryCtempCT, count - 1, tempRGB.red, 
tempRGB. green, tempRGB.biue); 
END; 


2 


FOR count := 1 TO 360 DO 
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BEGIN 
BumpCTEntru(tempCT); 

DoDelau(1); 

AnimatePaletteCMyWindow[rainbowW], tempCT, Ø, 2, 
120); 


END; 
DisposHandle(Handle(tempCT)); 
END; 


(*xXXxXXXX1X515XXX53XXX Fade ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ххх) 
(Demonstrates the Fade effect) 


(Create the Fade Animation Window Cuses Palette resource).) 
PROCEDURE MakeFade; 
BEGIN 

js MyWindow[fadeW] := GetNewCWindow(FadeID, NIL, POINTERC- 


END; 


(Draws Fade window) 
PROCEDURE DoFadeUpdate; 
VAR 
tempRect : Rect; 
count : INTEGER; 
BEGIN 
PmF oreColor(@); 
SetRect(tempRect, -32000, -32000, 32000, 32000); 
PaintRectCtempRect); 


FOR count := 1 TO 4 DO 
BEGIN 
PmForeColor(count); 
SetRectCtempRect, CCcount - 1) х 100) + 10, 10, 
(count * 100) - 10, 90); 
PaintOvalCtempRect); 
END; 


FOR count : 5 TO 8 DO 
BEGIN 

PnForeColor(count); 

SetRect(tempRect, CCcount - 5) * 100) + 10, 110, 
(Ccount - 4) * 100) - 10, 190); 
PaintOvalCtempRect); 
END; 
END; 


(Animate the Fade.) 
PROCEDURE AnimFade; 
CONST 
FadeStep - 60; 
AR 


count, E : INTEGER; 
Buf, Inc, Start : ARRAY[0..8] OF RGBColor; 
BEGIN 
SetRGBCBuf [Ø], -1, -1, -1); 
SetRGB(Buf [1], Ø, 0, 0); 
SetRGBCBuf [2], -1, В, 0); 
SetRGB(Buf [3], 0, -1, Ø); 
SetRGB(Buf [4], Ø, Ø, -1); 
SetRGB(Buf [5], 0, -1, -1); 
SetROB(Buf [6], -1, В, -1); 
SetRGB(Buf [7], -1, -1, 0); 
SetRGBCBuf [8], 30000, 30000, 30000); 
FOR E := 0 TO 8 DO 
BEGIN 
CopyRGB(Buf [E], Start[E]); 
UnSignedDiv(Buf [E].Red, FadeStep, Inc[E].Red); 
UnSignedDiv(Buf[E].Green, FadeStep, 
Inc{E].Green); 
UnSignedDiv(Buf [E].Blue, FadeStep, InclE].Blue); 


4 
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FOR count := FadeStep - 1DOWNTO 1 DO 
BEGIN 
FOR E := 0 TO 8 DO 
BEGIN 


DoDelay(C 1); 

UnSignedSub(Buf [E].Red, Inc[E].Red); 
UnSignedSub(Buf [E]. Green, Іпс(Е1.0гееп); 
UnSignedSub(Buf [EJ.Blue, Inc[EJ.Blue); 
AnimateEntryCMyWindow[fadeW], E, Buf [E2; 
END; 
END; 


DoDelay( 1); 
FOR E : 0 TO 8 DO 


EGIN 
SetROBCBuf [E], Ø, В, 0); 
AnimateEntryCMyWindow[fadeW1, E, Buf (ЕЈ); 


END; 
DoDelay(90); 
FOR count := 1 TO FadeStep - 100 
BEGIN 
FOR E := 0 TO 8 DO 
BEGIN 
DoDelay( 1); 
UnSignedAdd(Buf [EJ.Red, Inc[E].Red); 
UnSignedAdd(Buf [Е] .бгееп, Inc[E].Green?; 
UnSignedAdd(Buf [EJ.Blue, Inc{E].Blue); 
AnimateEntryCMyWindow[fedeW], Е, Buf (E12; 
END; 
END; 
DoDe lay( 1); 


FORE := 0 TO 8 DO 
AnimateEntryCMyWindow[fadeW], E, Buf ЕЈ); 
END; 


UNIT PalFunGlobals; 
INTERFACE 
USES 
ROM85, ColorQuickDraw, ColorWindowMgr, PaletteMgr, 
Picker Intf; 


( Global Constants } 


CONST 
eppleM = 301; (Menu ID Constants) 
fileM = 302; 
editM = 303; 
winM = 304; 


menuCount = 394; 


numWindows = 9; (Window ID Constants) 


redW - 1; 

greenW - 2; 

blueW = 3; 

curW = 4; 

ballW = 5; 

shapeW = 6; 

reinbowW = 7; 

fadeW = 8; 

StrID - 300; (Various Resource ID Constants} 


AlertID - 300; 
FadeID = 300: 
ShapeID = 301; 
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МахСТ = 2048; (Мах Numbers in CLUT Cusually only 256) 


ColorInc = %200; (Amount difference between Color rings) 
ColorStart = $FE00; (Start Color Rings) 


(My Version of the CLUT data structure Cused for stuff ing 
values).) 
TYPE 
MyCSpecArray = АЮКАҮ(0. .МахСТ] OF ColorSpec; 


MyCTabHandle = *MyCTebPtr; 

MyCTabPtr = ^MyColorTable; 

MyColorTable = RECORD 
ctSeed : LONGINT; 
ctFlag : INTEGER; 


ctSize : INTEGER; 
ctTable : MyCSpecArray; 
END; 


(Standard Variables (Menus, Window Pointer, Window Record)) 
(And Palette Handles (1 per Window). ) 
VAR 


myMenus : ARRAYLappleM. .menuCount] OF MenuHandle; 
MyWindow : ARRAY[1..numWindows] OF WindowPtr; 
MyPalette : ARRAY[1..numWindows] OF PaletteHandle; 


dregRect : Rect; 
doneFlag : BOOLEAN; 


IMPLEMENTATION 
END. 


File (bu seqment) 


MacPasLib 
MacTraps 
ROMSSLib 
ЕОМ85 
ColorQuickDraw 
Color Vindow Mgr 
PaletteMgr 
Picker Intf 
PalFun Globals 


Options 


[МГУ] 
[МГУ] 
[МУ 
ММ 
[N][V) 
[ЧГУ] 
[NIV] 


[D] 
[0] 
[0] 
[D] 
[D] 
[D] 
[0] 
[D] 


* PalFun.r - Resources for PalFun 
* by Steve Sheets for MacTutor 
x 


PalFun.RSRC 
2777777? 


Туре PASS = STR 
‚0 0 by convention 
Palette Animation by Steve Sheets M9 MacTutor 1988 


Туре BNDL 


PASS 0 
ICN* 1 
Ø 128 
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ҒКЕҒ 2 
0 128 


Туре FREF 


д 


APPL 0 ;; local id 0 for icon list 


Type SIZE - GNRL 
,71 
‚1 
16384 ;; $4000 = bit 14 set 
L 


192000 j; recomended 
L 
128000 ;; minimum 


Type ALRT 
,900 (0) 
40 170 140 470 
500 
4444 


Туре DITL 
900 (0) 


Button 
60 120 80 180 
OK 


staticText Disabled 
20 20 40 280 
“0 


Туре ALRT 
,300 (0) 
40 170 200 470 
300 
4444 


Туре DITL 
‚300 (0) 
5 


Button 
120 120 140 180 
OK 


staticText Disabled 
20 73 39 227 
PalFun by Steve Sheets 


staticText Disabled 
40 58 59 242 
Designed for MacTutor 3/88 


staticText Disabled 
60 15 79 285 
А demonstration of the Palette Manager 


staticText Disabled 
80 74 99 226 
and Palette Animation. 


Type MENU 
‚301 (0) 
\14 
- About PalFun... 
(- 


Туре MENU 
,302 (0) 

File 

Animate /А 
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Close/W 
(- 
Quit/Q 


Туре MENU 
‚303 (0) 

Edit 

Undo 

(- 

Cut 

Copy 

Paste 

Clear 


Type MENU 
‚304 (0) 

Window 

Red 

Green 

Blue 

Current Color 

Ball 

Shape 

Rainbow 

Fade 


Туре STR! 
‚300 (0) 
6 
Red 
Green 
Blue 
Current Colors 
Ball 
Rainbow 


Tupe WIND 

‚308 (0) 
Face 
120 140 420 520 
Visible GoAway 
0 


Туре WIND 

,300 (0) 
Fade 
100 100 300 500 
Visible GoAwau 
0 


Туре WIND 

‚301 (0) 
Shape 
140 120 280 370 
Visible GoAway 
0 
0 


Туре pltt = GNRL 
, 300 
‚Н 

0009 0000 0000 0000 0000 0000 0000 0000 
FFFF FFFF ҒҒҒҒ 0004 0000 0000 0000 0000 
0000 0000 0000 0004 0000 0000 0000 0000 
ҒҒҒҒ 0000 0000 0004 0000 0000 0000 0000 
0000 FFFF 0000 0004 0000 0000 0000 0000 
0000 0000 FFFF 0004 0000 0000 0000 0000 
0000 FFFF FFFF 0004 0000 0000 0000 0000 
FFFF 0000 FFFF 0004 0000 0000 0000 0000 
FFFF ҒҒҒҒ 0000 0004 0000 0000 0000 0000 
1530 7530 7530 0004 0000 0000 0000 0000 


Туре pitt = GNRL 
, 301 
‚Н 

0008 0000 0000 0000 0000 0000 0000 0000 
FFFF 0000 0000 0004 0000 0000 0000 0000 
0000 0000 FFFF 0004 0000 0000 0000 0000 
FFFF 0000 0000 0004 0000 0000 0000 0000 
0000 0000 ҒҒҒҒ 0004 0000 0000 0000 0000 
FFFF 0000 0000 0004 0000 0000 0000 0000 
0000 0000 FFFF 0004 0000 0000 0000 0000 
FFFF 0000 0000 0004 0000 0000 0000 0000 
0000 0000 ҒҒҒҒ 0004 0000 0000 0000 0000 


Туре clut = GNRL 
, 301 

.H 

0000 0000 0000 0007 
0000 FFFF 0000 0000 
0001 0000 0000 FFFF 
0002 ҒҒҒҒ 0000 0000 
0003 0000 0000 FFFF 
0004 FFFF 0000 0000 
0005 0000 0000 ҒҒҒҒ 
0006 FFFF 0000 0000 
0007 0000 0000 FFFF 


Туре clut = GNRL 
, 302 

‚Н 

0000 0000 0000 0007 
0000 FFFF 0000 0000 
0001 ҒҒҒҒ 0000 0000 
0002 0000 0000 FFFF 
0003 0000 0000 FFFF 
0004 FFFF 0000 0000 
0005 FFFF 0000 0000 
0006 0000 0000 ЕЕЕЕ 
0007 0000 0000 FFFF 


Туре clut = GNRL 
, 303 

‚Н 

0000 0000 0000 0007 
0000 ҒҒҒҒ 0000 0000 
0001 ҒҒҒҒ 0000 0000 
0002 FFFF 0000 0000 
0003 ҒҒҒҒ 0000 0000 
0004 0000 0000 FFFF 
0005 0000 0000 FFFF 
0006 0000 0000 FFFF 
0007 0000 0000 FFFF 


Туре ICN* = GNRL 
‚ 128 (4) ;; Тһе Appl. Icon 
H 


FFFFFFFF (0000003 BFFFFFFD 80000000 
AFFFFFF5 АС000035 ABFFFFDS АА000055 
ААТЕ0055 АА810055 ААВ 10855 АА811455 
АА812255 АА814155 ААТЕЗЕББ АА000055 
АА000055 АА007Е55 АА008155 АА108155 
АА288155 AA448155 АА828155 ААТСТЕББ 
АА000055 ABFFFFDS АС000035 AFFFFFF5 
В0000000 BFFFFFFD (0000003 FFFFFFFF 
x 

FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
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Pascal Procedures 
Serial Port Demo 


Just try to find out anything 
about how to talk to the Macs serial 
ports. I have looked in about 10-15 
books and they all seem to forget the 
these devices exist. You can see 
how to write to the screen, the disk, 
the printer, the system clock etc. 
What happened to the serial ports!!! 
They aren't so mysterious, as you 
will see. The only place I found any 
information about them is in Inside 
Macintosh. Anyone who has read 
Inside Macintosh knows that it is 
very difficult to follow as a tutorial, 
even by professional programmers. 
In many cases, a good example pro- 
gram, along with some discussion of 
the subject, will better help most 
programmers grasp the new tech- 
niques. "A Picture is worth a Thou- 
sand Words"!!! Ilearned about se- 
rial ports from a very basic terminal 
emulator. I just played with it and 
talked to other people about it. I will try to impart what I have 
learned to those interested. The sample program is derived from 
a Data Analyser program I wrote which can be used to examine 
data going back and forth between two serial devices. For 
example, from betweena printer and a computer or a modem and 
a computer. Our sample program displays one window for each 
serial port, and sends data typed at the keyboard out one port and 
in the other, where it is displayed in the port's window. This 
completely demonstrates both reading and writing to the Macin- 
tosh serial ports. 

A serial portis one of the computer's means to talk to the out- 
side world in which the data is sent onebitata time to some device 
such as a modem or printer. The Mac has 2 such ports at its 
disposal. Each port has two default buffers of 64 characters, an 
input and an output buffer. It seems that each buffer is set up in 
a circular fashion. 


General Circular Buffer Procedure 


A circular buffer works logically as shown in the graphic. 
Logically there is no end to the buffer. It just keeps going around 
in a circle. 

What actually happens in this type of buffer is that as a byte 
is received, it is put in the next position in the buffer. If the end 
of the buffer is reached, the byte is put at the start of the buffer 
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Serial Application 


Tom Scheiderich 
Fullerton, CA 
MacTutor Vol. 4 No. 6 


” é File Edit Baud Parity Bits oy 


SE ———À 


ut Pri Port B 


The words | type in window А are being sent out Port A and read in 
Port B and displayed in this window. If | click in window B here, Í 
my typing will be read and displayed in window А above! — 


Fig. 1 Output of our sample Serial Port Program 


overwriting whatever byte was there before. The users extracts 
these bytes from this buffer and put them into a work area (a 
character, byte or array). As each byte is received, a check must 
be made to see if the number of bytes in the buffer match the 
maximum number of bytes allowed in the buffer. Since we don't 
want to over- write these 
bytes, the pro- 8 | _ gram must then 
tell the device (modem, for 


example) not to ky send any more 
data until later. — Ё, M 2 


The device will 
then "go to sleep" until 
requested to 6 % ë 3 continue. This 
is called hand- Hep shaking. 
There 1$ no shift- с 4 ing of bytes as 
the data is read from and writ- 
ten to the buffer. The bytes will 


stay in the buffer as is, until over-written by new data. 

Inthefollowing example, we will assume that data is coming 
from a modem and is sending the word "TESTING". We have 
already received “TEST” and we are just going to read our first 
byte from the buffer. There are four control variables needed to 
handle the buffer. 


1. Buffer Size - This is the total number of bytes available in our 
buffer. 
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2. Get Byte - The next byte position in the buffer to read. 


3. Put Byte - The next byte position in the buffer available to 


put a byte. 


4. Byte Count - The number of bytes available in the buffer to 
read. This will be (Put Byte - Get Byte). If « O then add 


Buffer Size. 
CIRCULAR BUFFER EXAMPLE 


Assume the buffer already contains 4 bytes - ‘TEST’ and 
the buffer is 64 bytes long 


Serial Input Buffer 


а. 


5 Т 
| 2 É 4 5 6 7 8 


BUFFER SIZE - 64 
BYTE COUNT - 4 
GET BYTE - | 
PUT BYTE- 5 


At this point there are 4 bytes in the Buffer. The next byte 
we аге going to read is a “T” which is in byte #1. The next byte 
coming from the modem will go into byte #5. 


After reading a character 


DOGUOUMNBEN 
| 2 j 4 5 6 7 8 


BUFFER SIZE - 64 
` BYTE COUNT - 3 

GET BYTE - 2 

PUT BYTE - 5 


PROGRAM 1/0 BUFFER HUNE 


After the byte is taken from the circular buffer and put into 
a buffer specified by the program, the Byte Count will be set to 
3, which says there are now three bytes in the buffer to be read. 
The next byte to be read is in the 2nd byte position. This will be 
the letter "E". You will notice that nothing has happened to the 
"T" in position 1. 


After writing a character 


МИНЕ 


5 Т 
1 2 5 4 2 6 7 8 


BUFFER SIZE - 64 
BYTE COUNT - 4 
GET BYTE - 2 
PUT BYTE - 6 


Next character read from modem (1| 
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After the byte is put into the circular buffer, the Byte Count 
is then set to 4, which says there are now four bytes in the buffer 
to be read. The next byte read from the modem will be put into 
the 6th byte position. 


After writing a character, at the end of the buffer 


| 2 5 4 5 65 64 


BUFFER SIZE - 64 
BYTE COUNT - 64 
GET BYTE. - 2 
PUT BYTE - 2 


Next character read from modem НП 


Неге we are also putting a byte into the buffer but have run 
out of room. The next position would have been 65. Since this 
is greater than the Buffer Size, we now wrap around and put the 
byte in byte position 1, over-writing the “Т”, Also, you will 
notice that the Byte Count equals the Buffer size. We cannot 
acceptany more bytes until some bytes are taken out of the buffer, 
So we must perform some sort of handshaking to stop the modem 
from sending any more data. In the real world, this would happen 
before the buffer was full. The data could be coming so fast that 
by the time the modem has found out it is supposed to stop, it may 
have sent 20 more bytes. 


Macintosh Serial Ports 


Now we will see how this all applies to the Mac, which of 
course is our only reason for living. 


| | 
| 


с> 
C 
ct 
O 
c 
cr 
CU 
c 
= 
— 
MD 
“> 
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The Мас has two serial ports to choose from. Each of these 
ports has an input buffer and an output buffer. These are "our" 
circular buffers. Each buffer has a default size of 64 bytes. This 
can be changed to whatever size you want by acall to SerSetBuf. 
You don't have to worry about the control variables from our 
previous discussion of the circular buffers as these are handled 
internally by the Serial Drivers. The control variables were just 
to demonstrate how a circular buffer is handled. You may, 
however, want to know how many bytes are in the buffer at any 
one time. This is accomplished by a call to SerGetBuf. If the 
count returned is not equal to 0, then acall to FSRead is executed. 
FSRead will take the number of bytes requested out of the buffer, 
puts them into a buffer specified by the program and updates the 
buffers control words. The program can then do what it wishes 
with the data. For example, if running a terminal emulator, the 
bytes received might be text and can now be displayed to the 
screen. If receiving a file, the bytes might now be written to the 
disk. 

The sample program was written in Lightspeed Pascal. You 
should be able to see that dealing with the serial ports is very 
simple and not a mystery at all. The whole serial flow can be 
broken down to the following steps: 


1. Open and set up the Serial Port. 

2. Get any bytes that might be in the input buffer and deal with 
the data. 

3. Check if any keys have been pressed and write out the serial 
port 

4. Go back to # 2 and repeat. 


The actual flow is summarized here in the flowchart shown 
at the end of the article. 

In the example program, characters entered by the keyboard 
are written out one serial port and read into the other serial port 
and displayed on one of the two screens. 

Before we start looking at the program some important 
Serial port variables need to be understood: 


1. inBuffPtr - this is the 2k circular buffer that we are going to 
replace the default 64k buffer with. We set up the size and 
pointer to it (NewPtr) and then pass the pointer to the driver 
routine by way of SerSetBuf . We don't deal with it 
anymore from this point on. All of our dealings will be with 
inRefNum and outRefNum 

2. filterBuffPtr - the data returned from FSRead is put into this 
buffer. Since we will only be reading one character ata time, 
we only set up the buffer as one byte long. If we were going 
to read more than one byte from the buffer, you must set it 
up to the maximum number of bytes you might read. You 
may want to set the size the same as inBuffPtr . Unlike the 
circular buffers, the data being transfered will be put in the 
buffer starting from the first byte and continuing until all the 
bytes requested are transferred. 

3. inRefNum - this is the input channel (reference) number. 
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This number will be either a -6 (modem) or -8 (printer). All 
reading from the serial port will be done by referencing this 
number. It gets setup in RAMSDopen. 

4. outRefNum - this is the output channel (reference) number. 
This number will be either a -7 (modem) or -9 (printer). All 
writing to the serial port will be done by referencing this 
number. It gets set up in RAMSDopen. 


Each of these variables is set up as either "A" variables for 
the modem ports or “В” variables for the printer ports. For 
example, there is an inRefNumA for the modem and an 
inRefNumB for the printer. These are needed in our routine since 
we will be reading and writing to both of the ports. 

To change the default settings (9600 baud, 8 data bits, 2 stop 
bits and no parity), set SerConfig, which is an integer that has its 
bits set for the appropriate parameters and passed along with the 
reference number to SerReset. 

Handshaking is needed to prevent data overruns in the 
circular buffers. If no handshaking or the wrong handshaking is 
defined, you could get this overrun. Many of you have seen this 
with your printers when you are struggling to get the correct 
parity and stop bits setup. You will see a lot of garbage on your 
paper until you getit correct. This is caused many times because 
some data is getting lost when the printer has told your computer 
to stop sending, but because of incorrect settings, the computer 
kept sending data anyway and some of it was lost. 

You will need to set up a record of control bytes to tell the 
Mac what type of handshaking you want it to do and call 
SerHShake while passing this record. The record contains: 


1. fXOn - XOn/XOff output buffer flow control flag. If this is 
nonzero, then XOn/XOff flow control is enabled for the 
output buffer. 

2. fCTS - If nonzero, then hardware flow control is enabled. 
The handshaking will then be controlled by lines 4 and 5 of 
the serial port. 

3. хОп - What XOn character to use (usually a control-Q). 

4. xOff - What XOff character to use ( usually a control-S). 

5. errs - Tells the driver which type of errors cause input request 
to be aborted (parity, hardware overruns, or framing errors). 

6.evts- This byte tells whether changes in CTS or Break status 
will cause the driver to post device driverevents. This option 
is discouraged because interrupts are disabled for along time 
while events are being posted 

7. fInX - XOn/XOff input buffer flow control flag. If this is 
nonzero then XOn/XOff flow control is enabled for the input 
buffer. 


The type of handshaking we use here doesn't matter because 
everytime we send a character we also read it, so there is no way 
to get an overrun. But I have it set up as ХОп/ХОН for the input 
buffer only, using a control-S and a control-Q as our XOn/XOff 
characters for demonstration purposes. 

Before starting the program you will need to a special cable. 
They are very easy to build. Since we are dealing with XOn/ 
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ХОЙ, we need only 3 wires; the transmit, receive and ground 
wires. We аге building a null modem cable which is just a cable 
which reverses the transmit and receive lines. When we are 
transmitting out the modem port, we will be receiving through the 
printer port and vice versa. 


MINI-8 


Pin Assignments on the Serial Ports 


Following are the cable setups needed for the included 
program. To use the DB-9’s, if you are using a Mac Plus, Mac 
SE or a Mac II, you will need to purchase two - DB-9 to mini- 
8conversion cables. The DB-9 connectors are easier to deal with 
than the mini-8 connecters and both DB-9 connectors are male. 

To wire the cable, take the two male DB-9 connectors and 
wire them as shown in the figure below. Wire pin 3 to pin 3, 
ground. Wire pin 5 on one to pin 9 on the other for transmit. And 
finally, wire pin 9 on one to pin 5 on the other for receive. Then 
plug each male DB-9 connector into an Apple mini-8 to DB-9 
cable and plug the two mini-8 connectors into the modem and 
printer ports on the back of the Mac. The Apple cables are 
available at Apple dealers to convert the mini-8 serial ports to the 


| Output Handshake | Ground 
2 Input handshake/external clock 2 +5 volts 
5 Transmit data - $ Ground 
4 Ground 4 Transmit data * 
5 Receive data - 5 Transmit data - 
6 Transmit data * 6 *12 volts 
7 (not connected) 7 Handshake/external clock 
8 Receive data * 8 Receive data * 
9 Receive data - 


old style DB-9 connector devices used by the Mac 128 and Mac 
512 computers. If you are a wiz, you can try to make a mini-8 
cable instead, but we don't recommend it. 

The first thing that is done in our program is to open the serial 
ports which is done in the Init, Serial routine. We are using the 
RAM serial driver. Note that AppleTalk must be 
turned off at the chooser in order for this to work. АП 
buffers and pointers are set up here. Next we will set 
up the two windows shown in figure 1. 

The window selected is the port the data will be 
transferred out of and the other window is the port that 
will be doing the receiving. The non-selected win- 
dow will be the one we display the text on. 

Now we will just go into our normal “mainloop” 
routine. The first thing we will do is check for any 
bytes in the serial buffer (Get comm input). Ser- 
GetBuf is called to see if there are any bytes in our 
serial buffer. If there are, we will call FSRead (from 
GetChar) to get a character out of the buffer. Before 
writing to the window we need to call SetPort to select 
the correct window. If PortA is true, we are writing 
out the modem port and are displaying on window B, 
so we would then call SetPort(windowB) to select 
the second window and draw the character onto the 
screen (Put. Char). 

Last of all is to see if a key was pressed. If so, we 
need to write the character out the output port (Handle keys). A 
call would be made to FSWrite to transfer the character. 

The only other routine of interest would be RSerBuf which 
is called to reset the buffers and pointers and to reverse the input 
and output ports. This is done whenever a new window is 
selected or at the start of the program. Clicking in the content 
region of the unselected window, then reverses which window 
and port is doing the output and input of our characters typed on 
the keyboard. 


Wiring our null modem cable for port to port communications 
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Onelast thing. We are using the RAM Serial Driver for our 
program, but we could just as easily have used the ROM Serial 
Driver. The main problem is that the ROM Driver doesn't 
support XOn/XOff, so if this is necessary use the RAM Driver. 
If the ROM driver is needed then all that need be done is: 


Replace 
err] :=RAMSDOpen(sPor tA) 


With 
errI := OpenDriver(’.Ain’, inRefNum); 


еггі := OpenDriver(’ .Aout’, outRefNum); 


You need to explicitly open the input and the output Drivers. 


Open а Serial E 
Driver = 


wan 
ЕХЕЛЕКЕЕККЕКЕЛККЕКЛГЛЕЕКЕКККЕКККККЕКЕККЕКТСУНМ 


Im 
ирина ново 
Ta аі 


was а 


Flowchart for serial port operation 


UNIT Globals; 
INTERFACE 
CONST 
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rsrc = ‘SERL’; 

aAbout = 1; 

lastMenu = 408; ( number of menus ) 

eppleMenu - 403; ( menu ID for desk eccessory menu ) 
fileMenu - 404; ( menu ID for File menu ) 

editMenu - 405; ( menu ID for Edit menu ) 

baudMenu - 406; 

MessageDialog = 256; 

AboutDialog = 257; 

0300 = 1. 

b 1200 
b2400 
b4800 
09600 = 5; 
619200 = 6; 
parityMenu = 407; 
ПОР = 1; 

evenP = 2; 

oddP = 3; 
bitsMenu - 408; 


7 


7 
2; 
3; 
4. 
5, 


9 


| SE dps" p 
E a Я > 


bData7 = 1; 
bData8 = 2; 
bStopl = 4; 
bStop15 = 5; 
bStop2 = 6; 
----- serial port - - - - - - - ) 


inBuffLength = 2048; 
XONCHAR = 17; 


VAR 


XOFFCHAR = 19; 

CrRtn = 13; 

LineFeed = 10; 

muMenus : ARRAY[applemenu..lastMenu] OF MenuHandle; 
dragRect : Rect; 

doneFlag : BOOLEAN; 

myEvent : EventRecord; 


row, rowA, rowB, column, columnA, columnB, code, refNum 
: INTEGER; 


Call FSWrite to send 
one or more bytes 
out о ДЫ 


WindowA, WindowB, theWindow, whichWindow : WindowPtr; 
windowlines, NumWindows, theMenu, theItem : INTEGER; 
Charread : CHAR; 

Urgn : rgnhandle; 

savePort : GrafPtr; 

oneCount : Longint; 


serial port variables 

inBuffPtr, filterBuffPtr, outBuffPtr : Ptr; 
inBuffPtrA, filterBuffPtrA, outBuffPtrA : Ptr; 
inBuffPtrB, filterBuffPtrB, outBuffPtrB : Ptr; 


inRefNumA, outRefNumA : INTEGER; 
inRefNumB, outRefNumB : INTEGER; 
inRefNum, outRefNum, err : INTEGER; 


serConfig, (sum of following vars} 
baud, parity, deteBits, stopBits : 
portA : Boolean; 


INTEGER; 


IMPLEMENTATION 


Cannot open Ram serial 
driver Real B 

Try turning off 
RppleTalk in Chooser 


Typical Error produces this error message 
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UNIT initprogram; 
INTERFACE 


USES 
Globals, Misc; 


PROCEDURE 1п1{а11; 
IMPLEMENTATION 
PROCEDURE SetUpMenus; 


VAR 
i : INTEGER; 


BEGIN 
InitMenus; ( initialize Menu Manager ) 
myMenusLapplemenu] := GetMenuCappleMenu); 
AddResMenu(myMenus [applemenul, ‘DRVR’); 
( desk accessories ) 
nyMenus[f ilemenu] := GetMenuCf ileMenu); 
myMenus [editMenul :- GetMenuCeditMenu); 
myMenus[baudMenu] := GetMenuCbaudMenu); 
myMenus[parityMenu] := GetMenu(parityMenu); 
myMenus[bitsMenu] := GetMenu(bitsMenu); 


FOR i := applemenu TO lastMenu DO 
InsertMenuCmyMenuslil], 0); 
DrawMenuBar ; 
END; ( of SetUpMenus ) 


(—— set up serial port parameters ——) 
PROCEDURE Init_serial; 


VAR 
еггі : INTEGER; 
Hand : SerShk; 


BEGIN 


( Pointers to buffers need to be set up - we are setting up 
for 2k end overriding 64 byte default. Note very simple error 
checking using а vanilla dialog box routine doMessage. ) 


inBuffPtrA := NewPtrCinBuffLength); 
filterBuffPtrA := NewPtr(1); 
inBuffPtrB :- NewPtrCinBuffLength); 
filterBuffPtrB := NewPtr(1); 


еггі := RAMSDOpenCsPortA); 
( open modem port - sPortA is already def ined ) 
IF errI © noErr THEN 
doMessage( ‘Cannot open Ram serial driver Real А”, 
‘Try turning off Appletalk in Chooser’, “2, ‘’); 


2 


еггі := RAMSDOpen(sPor tB); | 
( open printer port - sPortB is already defined ) 
IF еггі € noErr THEN 
doMessage( ‘Cannot open Кат serial driver Real В”, 
‘Try turning off AppleTalk in Chooser’, ‘’, 49); 


inRefNumA := AinRefNum; (driver reference number = -6) 
outRefNumA := AoutRefNum; (driver reference number = -7) 


inRefNumB :- BinRefNum; (driver reference number = -8) 
outRefNumB := BoutRefNum; (driver reference number = -9) 


(set baud rate, parity, etc. for both in and out) 


baud := 94; (1200) 
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parity := 0; (none) 
deteBits := 3072: (8) 
stopBits :- 16384; (1) 


“ 


serConfig := baud + parity + dataBits + stopBits; 


( Note we are lazy now, по error checking! You should check ) 


еггі := SerResetCinRefNumA, serConf ig); 


( set modem input ) 


errI :- SerResetCoutRefNumA, serConf ig); 


( set modem output ) 


errI :- SerResetCinRefNumB, serConf ig); 


( set printer input ) 


еггі := SerResetCoutRefNumB, serConf ig); 


( set printer output ) 


( set handshaking of ports for xon/xoff ) 


WITH Hand DO 
BEGIN 

FXON := 0; 
FCTS := 0; 
ХОМ := CHARCXONCHAR); 
ХОҒҒ := CHARCXOFFCHAR); 
ERRS := 
EVTS := 
ЕМХ :- 

END; 


ErrI := SerHShekeCinRefNumA, Hand); 
ErrI := SerHShakeCinRefNumB, Hand); 


C 
Ü 
Ü 
1 


д 
. 
9 
7 


(set buffer) 


err 


( initially set I/0 ports to the modem ports ) 


inRefNum :- inRefNumA; 
outRefNum := outRefNumB; 


END; (Init. serial) 
PROCEDURE initall; 
VAR 


err : integer; 


BEGIN 


END; 
END. 


MoreMasters; (create 64 master pointers - for future) 


MoreMasters; 
MaxApplZone; 
InitGref CéthePort); 
InitFonts; 
FlushEventsCeveryEvent, 0); 
InitWindows; 
SetUpMenus; 
init_serial; 
TEInit; 
InitDialogsCNIL); 
HideAll; 

Urgn := newRgn; 
SetCursor(arrow); 
SetRect(dragRect, 4, 24, 508, 338); 
doneFlag := FALSE; 
portA := true; 

row := 1; 

oneCount := 1; 
windowlines := 9; 
column := 1; 
numWindows := 0; 


еггі := SerSetBufCinRefNumA, inBuffPtrA, inBuffLength); 
I := SerSetBufCinRefNumB, inBuffPtrB, inBuffLength); 
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UNIT menus; ! BEGIN 
resetmodem :- false; 


INTERFACE CASE whichMenu ОҒ 
baudMenu : 
8 BEGIN 
0100816, GPLib, Misc; Place checkmarksCbaudMenu, 5300, b19200, 
whichItem); 
PROCEDURE DoCommand (mResult : LongInt); resetmodem :- true; 
CASE whichItem ОҒ 
IMPLEMENTATION 6300 : 
baud := 380; 
PROCEDURE doAbout ; b1200 : 
VAR beud := 94; 

IDStrHandle : StringHandle; 02400 : 

dialogP : DialogPtr; baud := 46; 

item : integer; 04800: 

бігі, Str2, Str3 : str255; baud := 22; 

myHeapSpace : LongInt; b9600 : 

FreeSpace : Size; baud := 10; 

BEGIN b19200 : 
I0StrHandle := StringHandleCGetResource(rsrc, 022; baud := 4; 
IF IDStrHendle = NIL THEN END; (CASE whichItem) 

BEGIN END;  (baudMenu) 

doMessage( ‘Get About box crash!’, '^, '', 4%; 
ExitToShe11; parityMenu : 

END; BEGIN 
MoveHHiCHaendleCIDStrHandle)); Place.checkmarks(CpaerituMenu, noP, oddP, 
HLockCHandleCIDStrHendle22); whichItem); 

FreeSpace := FreeMem; resetmodem := true; 
myHeapSpace := MaxMem(FreeSpace); CASE whichI tem ОҒ 
NumToStr ing(myHeapSpace, Str2); noP : 

Str2 := concatC'Memory = ', Str2); parity := 8192; 
Str3 (5 “2, evenP : 

Stri := °’; paritu := 12288; 
PeremTextCIDStrHandle^^, Stri, Str2, Str3); oddP : 

dialogP := GetNewDialog(AboutDialog, NIL, pointer(-1)); paritu := 4096; 
IF dialogP = NIL THEN END; (CASE whichItem) 

BEGIN END; (parityMenu) 

doMessage( ‘Dialog crash!’, ‘We are dead...’, ‘’, 

e bitsMenu : 

ExitToShe11; BEGIN 

END; resetmodem :- true; 
initCursor; IF whichItem < 3 THEN 
ModalDialog(NIL, item); Place_checkmarks(bitsMenu, bData7, bDatad, 
DisposDialog(dialogP); whichItem) 

HUnlockCHaendleCIDStrHandle2); ELSE 
END; Place_checkmarks(bitsMenu, bStopi, bStop2, 
whichItem); 
CASE whichItem OF 
bData! : 
Serial Demo dataBits := 1024; 
bDates : 
Shows Serial Port Use Sere 
Serial Demo set up for stopBits := 16384; 
MacTutor by Tom Scheiderich ЫЅќор15 : 


StopBits := -32768; 
bStop2 : 
stopBits := -16384; 
END; (CASE whichItem) 
END; (bitsMenu) 


END; (CASE whichMenu) 


- Rpril 21, 1988 


Memory - 826752 


About box code above puts up this dialog 


IF resetmodem THEN 


BEGIN 
; , serConfig := beud + parity + dateBits + stopBits; 
mM седан Do_comm_commands (whichMenu, whichItem : errC := SerResetCinRefNumA, serConfig); 
д errC := SerResetCoutRefNumA, serConf ig); 
VAR errC := SerResetCinRefNumB, serConf ig); 
errC : INTEGER: errC := SerResetCoutRefNumB, serConf ig); 
: END; 


resetmodem : boolean; 
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END;  (Do.comm commands) 


PROCEDURE DoCommand; (CmResult : LongInt)) 
VAR 
nàme, command : STR255; 


BEGIN 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 
CASE theMenu OF 
appleMenu : 
IF theItem = aAbout THEN 
doAbout 
ELSE 
BEGIN 
GetItem(myMenuslapplemenu], theltem, 
name); 
refNum :- OpenDeskAcc(name); 
END; 
fileMenu : 


VA the! ten OF 


 doneFlag : = TRUE; ( Quit ) 
END; ( thelten case ) 


OTHERWISE 


Do_comm_commands( theMenu, theItem), 
END; ( of menu case } 


HiliteMenuC0); 
END; ( of DoCommand ) 
END. 


UNIT GPL ib; 


INTERFACE 


USES 
Globals; 


PROCEDURE RSerBuf Coutref : integer); 
PROCEDURE GoToXY (x, y : integer); 


PROCEDURE Place. checkmarks (menuId, firstItem, lastItem, 


chosenItem : Integer); 
PROCEDURE NewWindows; 
PROCEDURE SelectNewW indow:; 


IMPLEMENTATION 


( reset the 1/0 variables and buffers } 


PROCEDURE RSerBuf; ^ (Coutref : integer);) 
BEGIN 
IF outrefnum € outref THEN 
( reset port 1/0 variables and buffers } 
BEGIN 


IF outrefNumA = outref THEN 
(set to the ‘A’ buffers and variables } 
BEGIN 
outrefNum := outrefNumA; 
inrefNum := inrefNumB; 
inBuffPtr := inBuffPtrB; 
filterBuffPtr := filterBuffPtrB; 
RowA :- Row; 
row :- RowB; 
ColumnA := Column; 
Column := ColumnB; 
SetPort(WindowB); 
theWindow := WindowB; 
END 
ELSE 


O The Definitive MacTutor, Vol. 4 


BEGIN 

(set to the ‘B’ buffers and variables ) 
outrefNum := outrefNumB; 
inrefNum := inrefNumA; 
inBuffPtr := inBuffPtrA; 
filterBuffPtr := filterBuffPtrA; 
RowB := Row; 
row := RowA; 
ColumnB :- Column; 
Column := ColumnA; 


SetPortCWindowA); 
theWindow := WindowA; 
END; 


END; 
END; 


( set the position for the next character to be displayed ) 
PROCEDURE GoToXY; 
VAR 
I, J : integer; 


BEGIN 
I := x * 6; 
J := U * 12-2; 


moveto(I, J); 
ND; 


д 


PROCEDURE Place-checkmarks; ^ ((menuId, firstItem, 
lastItem, chosenItem : Integer) 
VAR 


index : Integer; 


BEGIN 
FOR index := firstItem TO lastItem DO 
checkItem(myMenus[menuID], index, False); 
CheckItemCmyMenus (menuID], сһовеп tem, True); 
END; (Place_checkmarks) 


( open a new window and set it’s characteristics ) 
PROCEDURE NewWindows; 


BEGIN 
numWindows :- numWindows * 1; 
IF numWindows = 1 THEN 
( modem port A ) 
theWindow := GetNewWindow(254, NIL, PointerC- 15); 
IF numWindows = 2 THEN 
( printer port B ) 
theWindow := GetNewWindow(255, NIL, Pointer(- 125; 
setPortCtheWindow); 
TextFont(monaco); 
TextSize(9); 
ShowWindowCtheWindow); 
Row := 1; 
Column := 1; 
END; 


( select the window selected by the user ) 
PROCEDURE SelectNewWindow; 


BEGIN 
SelectWindowCwh ichWindow); 
theWindow := whichWindow; 


IF theWindow - windowA THEN 
BEGIN 
portA := true; 
RSerBuf CoutrefnunA); 
( reset the I/0 buffers and variables ) 
END 
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LSE 
BEGIN 
portA := false; 


RSerBuf CoutrefnumB); 
( reset the 1/0 buffers апа variables ) 
END; 
END; 
END. 


UNIT HendleChers; 
INTERFACE 


SES 
Globalis, GPLib; 


PROCEDURE DisplayChar (charread : cher); 
PROCEDURE Put_Char Ctempcher : integer, 

CharRead : Char); 
PROCEDURE Handle_keys (keyPressed : Cher); 
PROCEDURE Get. comm input; 


IMPLEMENTATION 


PROCEDURE DisplayChar; (Ccharread : char?) 
BEGIN 
gotoxyCcolumn, row); 


drawcher (charread); 
column := column + 1; 
END; 
PROCEDURE Put.Cher; ( Ctempchar : integer;CharRead : 
Cher?) 
BEGIN 
CASE tempchar OF 
CrRtn, LineFeed : 
BEGIN 
IF row <= windowlines THEN 
row := row + 1 
ELSE 
BEGIN 
ScrollRectCthePort^.portRect, 0, -12, гоп), 
END; 
Column := 1; 
gotoxy(column, row); 
END; 
OTHERWISE 
Disp layChar (CharRead ); 
END; (tempchar } 
END; 


(— handle all keyDown events, including command-keys —) 
PROCEDURE Handle_keys; ((keyPressed : Char?) 


VAR 
oneChar : LongInt; 
cherAddr : Ptr; 


BEGIN 
onecher := 1; 
charAddr := POINTERC1 + ORD4CEekeyPressed)); 
(char in low-order byte of word) 


err := FSWriteCoutRefNum, oneChar, charAddr); 
(send out serial port) 
END; (Handle keys) 


( get the next character from the input buffer currently 
selected ) 
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PROCEDURE GetChar (VAR хсһаг : char); 
VAR 
errorCode : Integer; 


BEGIN 


errorCode := FSReadCinRefNum, oneCount, filterBuffPtr); 


Xchar := Chr(filterBuffPtr*); 
( get the character pointed to by filterBuffPtr ) 


BitCl1r(@XChar, 8); (clear the high bit for ascii data, 


not used for binary date) 
END; 


(—get characters from serial port, and filter — 
PROCEDURE Get. comm. input ; 


VAR 
errorCode, tempchar : INTEGER; 
inCount : LongInt; 


BEGIN 
errorCode := SerGetBuf CinRefNum, inCount); 
(get * of char in input buffer) 


( — use the code below to very SLOWLY strip line feed 
charecters — ) 
IF inCount » 0 THEN 
BEGIN 
GetChar (Charread); 
IF ord(charRead) ‹ 0 THEN 
BEGIN 
tempchar := BitAndCordCcherRead)2, 127); 
( clear the high bit } 
IF CportA) THEN 
setpor tCwindowB) 
( we are writing out port A, we are reading port B ) 
E 


setportCwindowA); 
(че are writing out port B, we ere reading port А ) 
Put -CharCtempchar, cherRead) 
END; (if charRead) 
END; (if "incount) 
END; (Get_Comm_input) 
END. 


UNIT Misc; 
INTERFACE 


USES 
Globals; 


PROCEDURE doMessage (messaged : str255; 
messagel : str255; 
message2 : str255; 
messages : str255); 


IMPLEMENTATION 


PROCEDURE doMessage; ((message® : str255) 
(message! : str255) 
(nessage2 : str255) 
(nessage3 : str255)) 
VAR 
dialogP : DialogPtr; 
item : integer; 
BEGIN 
ParanText (messaged, message l, message2, messages); 
dialogP : = ve МекПі1В125(5553906038100; NIL, pointer(-1)); 
IF dialog? = NIL THEN 
BEGIN 
SysBeep(5); 
ExitToShell; 
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END; 
initCursor; (change to arrow) 
ModalDialog(NIL, item); 
DisposDialogCdialogP); 
END; 


МасРа ЛЬ 
МасТгар$ 
ММ] Globals.pas 
ММУ] R GPLib.pas 


ММе  HandleChars.pas 
СММ] Serial.pas 


А 


Units аге linked as shown above 


PROGRAM Serial. Demo; 


Serial.Pes) 
Serial.R) 


( Pascal source: 
( Resources: 


Globals, GPLib, HendleChars, initprogram, Menus, Misc; 
PROCEDURE mainloop; 
BEGIN 


SystemTask; 
Get.comm input; 
IF GetNextEventCeveryEvent, myEvent) THEN 
CASE nyEvent what ОҒ 
mouseDown : 
BEGIN 
code := FindWindow(myEvent . where, 


CASE code OF 
inMenuBar : 
DoCommandCMenuSelect(myEvent .where)); 
inSysWindow : 
SustemClick(muEvent, whichWindow); 
inDreg : 
IF whichWindow <> FrontWindow THEN 
SelectNewWindow 
ELSE 
DragWindow(whichWindow, 


whichWindow); 


myEvent.where, dragRect); 


inContent : 
IF whichWindow <> FrontWindow THEN 
SelectNewWindow; 
END; ( of code cese ) 
END; ( of mouseDown ) 
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keyDown, autoKeu : 
Handle. keysCchrCLoWord(myEvent .пеззаде))); 


activateEvt : 
BEGIN 


whichWindow := WindowPtr(myEvent .message); 


IF ODD(nyEvent .modif iers) THEN 
Se tPor t(whichWindow); 
END; ( of activateEvt ) 


updeteEvt : 
BEGIN 
GetPort(savePort?); 
whichWindow :- WindowPtr(myEvent .message); 


SetPortCwhichWindow); 
BeginUpdateCwhichWindow); 
EndUpdateCwhichWindow); 
SetPort(savePort); 
END ( of updateEvt ) 
END ( of event case ) 
END; 


BEGIN ( main program ) 
initall; 
UnloadSeg(@initall); 
newWindows;  ( open the Printer window - В - first ) 
rowB := row; 
columnB := column; 
WindowB :- theWindow; 
newWindows;  ( open the modem window -A) 
rowA := row; 
colum := column; 
WindowA := theWindow; 
RSerBuf CoutrefnumA); 
REPEAT 
mainloop; 
UNTIL doneF lag 
END. 


х Serial.R 
x 


Serial/Rsrc.rsrc 
27777777 


Type SERL = STR 
0 


7 
Serial Demo set ир for MacTutor by Tom Scheiderich - April 
21, 1988 


Type FREF 
,128 
APPL Ø 


Type BNDL 


Type MENU 
, 403 
V 14 ,,8pple menu 
About Serial.. 
(- 


, 404 
File 
(Open 
(New Window 
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(- 

(Save 
(Save As... 
(- 

Quit 


, 405 
Edit 
(Undo /Z 


(Copy/C 


12001412 
2400 
4800 
9600 
19200 


‚407 
Parity 
None! \ 12 
Even 
Odd 


, 408 
Bits 
7 Data 
8 Вафа! \ 12 
(- 
1 ${ор!\12 
1.5 Stop 
2 Stop 


Type WIND 

Out Modem Port - А 
40 10 178 500 
inVisible NoGoAway 
0 

0 


Туре WIND 

Out Printer Port - B 
200 10 330 500 
inVisible NoGoAwau 

0 

0 


* —— Multifinder events — 


* bit 15 = switcher save screen 
* bit 14 = accept suspend resume events 


* bit 13 = switcher enable option switch 


X bit 12 
events 

* bit 11 = multifinder aware 

x Cactivates & deactivates 


can do background on null 


topmost 
* window at resume, suspend 
events) 


Type SIZE - GNRL 
,"1 
‚Н 
4800 ;; $4800 = bits 14,11 set 
L 
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128000 ;; (for 150К recomended) 
le 

80000 ;; (Гог 80K minimum) 

1 


* Ргодгат Messages Dialog box... 
type DLOG 
,256 
Program Messages 
100 100 200 400 
Visible NoGoAway 
1 


0 
256 


{уре DITL 
,256 
3 

Віл {ет Enabled 
65 230 95 285 
OK 


StatText Disabled 
15 68 85 222 
^0N20^ 11007210073 


IconItem Disabled 
19 18 42 42 
1 


x — Dialogs —— 
ж About Box dialog... 
{уре DLOG 
,251 
About Serial.. 
100 100 250 400 
visible NoGoAway 
1 
0 
257 


{уре DITL 
‚251 


3 
BtnItem Enabled 
112 235 141 284 
OK 


StatText Disabled 

10 88 141 289 

Serial Оето\@0\00++ 
Shows Serial Port 
UseMV2D^ 2X0D^ 11007210073 


PicItem Disabled 
10 10 96 81 
128 


Туре ICN# = GNRL 
,128 (0) 

.H 

0001 0000 0002 8000 0004 4000 0008 2000 
0010 1000 0021 C800 0040 C400 0081 4200 
0102 0100 0204 0080 0408 0040 0810 0020 
1020 0010 2040 0008 4280 3F04 8300 4082 
4381 8041 2003 3022 1005 C814 080Е TF8F 
0402 3005 0201 0007 0100 8005 0080 6007 
0040 ІҒЕ5 0020 021Ғ 0010 0407 0008 0800 
0004 1000 0002 2000 0001 4000 0000 8000 
0001 0000 0003 8000 0007 С000 000Ғ Е000 
00ІҒ Ғ000 003Ғ Ғ800 007Ғ ҒС00 00ҒҒ ҒЕ00 
@1FF FF00 O3FF ҒҒ80 O7FF FFCO OFFF FFEO 
ІҒЕҒ ЕЕЕ@ ЗҒҒҒ FFF8 ТЕРЕ ЕРЕС FFFF ҒҒҒЕ 
TFFF FFFF 3FFF FFFE 1FFF FFFC ОҒҒҒ ҒҒҒҒ 


Q7FF FFFF @ЗЕЕ FFFF @1FF FFFF ØØFF FFFF 
007F FFFF 003F FEIF @01Е ҒС07 BØF Ғ800 
0007 Ғ000 0003 Е000 0001 CODO 0000 8000 


TYPE PICT = GNRL 
‚ 128 

891 

195 254 281 325 

.H 

1101 А000 82A0 008Е 0100 0400 0000 0002 
0002 4098 000А 00С3 00-8 00ҒҒ 0148 00С3 
Й0ҒЕ ØØFF 0145 00C3 00ҒЕ 00ҒҒ 0145 0000 
02Е7 0002 Ғ700 02Ғ7 0002 Ғ700 02Ғ7 0002 
F700 02Ғ7 0002 Ғ700 02Ғ7 0002 Ғ700 02Ғ7 
0006 Ғ000 000Е ҒС00 O7FD 0001 1Ғ80 Ғ000 
O7FD 0001 7ЕСВ FDOO Ø7FD 0001 FFFO Ғ000 
@8FE 0002 O3FF FCFD 0008 ҒЕ00 0207 FFFE 
Ғ000 09ҒЕ 0003 1FFF ҒҒ80 ҒЕ00 09ҒЕ 0003 
3FFF ҒҒЕй FE00 @ОРЕ 0003 ТЕРЕ FFF8 ҒЕ00 
0402 0000 O1FE ҒҒ00 FCFE 0008 0200 0003 
FDFF ҒЕ00 0А02 0000 OFFD ҒҒ00 COFF 0008 
0700 001F FFFF 3FFF EOFF 0008 0700 007Ғ 
FFFE 1FFF F8FF 0008 0700 ØØFF FFFE IFFF 
FCFF 0008 0100 @1РЕ FF02 27FF FCFF 0008 
0100 В1ЕЕ FF02 FOFF F8FF 0008 0100 00ҒЕ 
FF02 ҒЕТЕ FOFF 0008 0200 003Ғ FEFF 019Ғ 
EOFF 0008 0200 00ІҒ FEFF 01Е7 COFF 0008 
0200 003Ғ FEFF 01Ғ9 80FF 0008 0200 0033 
FEFF @1FE 80ҒҒ 000А 0200 0060 ҒОҒҒ 00С0 
ҒҒ00 0807 0000 607Е FFFF FCCO ҒҒ00 0807 
0000 601F FFFF Ғ870 ҒҒ00 0807 0000 6007 
FFFF FOF8 ҒҒ00 0807 0000 6001 FFFF FOF8 
FF00 0807 0000 6000 FFFF FOF8 ҒҒ00 0807 
0000 6038 3FFF В050 ҒҒ00 0А06 0000 607С 
OFFF 30ҒЕ 0008 0700 0060 Ғ603 РЕЗО ABFF 
0008 0700 0060 E301 FC30 50ҒҒ 0008 0700 
0060 (000 7830 20FF 0008 0700 0060 0000 
1030 B8FF 0008 0200 0060 ҒЕ00 0130 50ҒҒ 
0004 0200 0060 ҒЕ00 0030 ҒЕ00 0802 0000 
6OFE 0001 30А8 ҒҒ00 0807 0000 6807 0700 
В050 ҒҒ00 0А06 0000 681F 8ҒСФ ВОРЕ 0008 
0700 006С ТЕОЕ F180 АВЕЕ 000A 0200 0067 
FEFF 0030 ҒЕй0 0809 0000 63FF FFFE 31F4 
1000 0809 0000 307F DFFØ 6046 3000 0809 
0000 381F ВЕС Е045 5000 0809 0000 1С00 
0001 C044 9000 0809 0000 0Е00 0003 8044 
1000 0802 0000 O7FE FFFD 0009 0500 0001 
FFFF FCFD 0008 ҒЕ00 0280 0004 Ғ000 9800 
OAJO ҒҒ00 Ғ801 1901 4800 ҒҒ00 FEO! 1901 
4500 FFØØ ҒЕй1 1901 4500 0008 ҒЕ00 0280 
0004 Ғ000 08ҒЕ 0002 FFFF FCFD 0008 0200 
0001 FEAA FDOO 0802 0000 03ҒЕ 55FD 000А 
0600 0006 FEAF ЕА80 ҒЕ00 0А06 0000 0083 
5835 40FE 000A 0600 0018 0180 1AA ҒЕ00 
ЙАй6 0000 3501 5015 50ҒЕ 000А 0600 006А 
82А8 2ААВ FEØØ 0А0б 0000 0570 5707 ҒАҒЕ 
000A 0600 O1AF ААРА АСТА ҒЕ00 0А06 0003 
5055 0558 0ОҒЕ 0008 0700 06А0 2A02 АВА 
80FF 0008 0700 0060 3603 5415 40ҒҒ 0008 
0700 0ABO 6806 ABEA COFF 0008 0700 005Ғ 
0520 5555 40FF 0009 0100 OAFC АА00 COFF 
0009 0100 BDFC 5500 40FF 0000 0100 ØFFC 
FF00 COFF 0002 Ғ700 02Ғ7 0002 Ғ700 02Ғ7 
0002 Ғ700 02Ғ7 0002 Ғ700 А000 BFAD 0083 
FF 


рч! 


EPS 
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Advanced Mac'ing 
Menus as Objects in TML Pascal 


[One of the limitations of LightSpeed Pascal and Turbo 
Pascal, despite their popularity, is that they don't support 
objects. TML Pascal does support the object type, which is 
similar to a procedure. In this article, David Curtis shows us how 
to use the TML Pascal Object type on menus to create an elegant 
way to manage menus, especially a custom menu definition like 
an icon menu, shown in figure 1 . Unfortunately, Tom Leonard of 
TML has not bothered to keep MacTutor supplied with updates 
to TML Pascal in over a year, so I have been unable to check the 
compilation and linking of this article. However, the code looks 
clean and should not have any problems. It is our hope that TML 
will keep MacTutor and the rest of the development community 
better informed and supplied with timely updates to their Pascal. 
-Ed] 

In some applications, a graphic menu provides a friendlier 
user interface than the standard text list. MacDraw's “Fill”, 
"Lines", and “Реп” menus are good examples. They show you 
the patterns you can choose from, rather than describe them in 
words. Can you imagine trying to describe the SysPat list 
verbally? Pictures are much more friendly. I have a similar 
problem in an application I am working on. It is a simple circuit 
analysis program, and I wish to have a menu of circuit models for 
the user to choose from. A circuit element is much more easily 
drawn than described. The brute force approach to this problem 
is to make a procedure that draws each circuit model in the menu 
area. That works, but I dislike it. Firstofall, itis hard to maintain. 
Second, it is just plain hard work to build the first time. Finally, 
it is code that has little hope of ever being useful in another 
program. 

In case you didn't notice, my objections to the brute force 
approach are motivated largely by sloth. How could I avoid 
excess work, both now and in the future? I went out in search of 
the lazy man's way to a widely applicable, easily maintainable 
graphic menu, and came up with the icon menu. The icon menu 
procedure uses icons from a resource file to present a palette of 
selections. The code is generic across any application, and the 
icons can be maintained easily with ResEdit. Icons turn out to be 
a very nice size for my circuit model pictures. I suspect that icons 
would be good for a lot of graphic menu applications. (How 
about an icon based Transfer menu?) Figure 1 shows a prototype 
circuit model menu, implemented as an Icon menu. 


Implementation Overview 
Iimplemented the icon menu as a TML Pascal UNIT. (Any 


code that might get used in another program in the future I 
automatically put into a UNIT.) The OBJECT feature of Pascal 
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Fig. 1 Icon Menus as Objects in Object Pascal 


is another powerful feature for reducing redundant work. I have 
used both features to create my icon menu, and usages of both аге 
several layers deep. Each layer is quite simple, but some sort of 
road map to the structure is in order. 

The lowest level unit is the trivial StdPoll (standard poll") 
unit. I mention it only so that you don't wonder why I didn't. 
Eventually, I plan to put generic polling loop code in here, but in 
its present form, StdPoll's main purpose is to provide the global 
variable "Done", which gets set in response to a “Quit” menu 
choice. Now on to the interesting stuff. 

StdMenu ("standard menu") is the key unit that everything 
is built upon. It defines a low level object called MenuHdlr 
(“menu handler"). A MenuHdlr object collects menu code into 
one place and “handles” all the associated behaviors. The two 
methods that a generic MenuHdlr has are Create, which should 
do whatever it takes to make a menu and insert it at the end of the 
menu bar; and Choose, which will be called to handle a menu 
choice. In the default case, Create just slurps up a normal menu 
resource from the resource fork. Choose, on the other hand, does 
nothing; it should be overridden in the application with appropri- 
ate code to handle the menu choices. 

The StdMenu unit also provides pre-defined descendant 
objects of МепіН г, called AppleMenuHdlr, StdFile- 
MenuHdlr, and StdEditMenuHdlr. These menu handlers pro- 
vide minimal functionality for the Apple, File and Edit menus, 
respectively. The AppleMenuHdlr should be all most applica- 
tions need to support a standard Apple menu. The Create method 
isoveridden with code that pulls in desk accessory names, and the 
Choose method is overidden with code that displays an 
"About..." alert, or opens a desk accessory. 

Notice that the AppleMenuHdlr has an additional method 
called "Setup", which does the additional pre-Create work of 
setting upanalert id for the About... selection. Ihave chosen the 
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convention of putting additional pre-create initialization for 
MenuHdirs (if needed) іп a Setup method, but Setup is not a 
method in the generic MenuHdlr. Why? Because every descen- 
dant object that overrides a method must have the same parame- 
ter list, and that is exactly what we don’t want fora Setup method; 
we want the Setup method to be specific to the needs of a sub- 
species of MenuHdlr. 

StdFileMenuHdlr and StdEditMenuHdlr exist in StdMenu 
only to provide bare minimum “Сһоове” functionallity. Most 
applications will want to override this code, but the minimal 
version is handy while prototyping other chunks of the applica- 
tion. 

The program TestMenus uses AppleMenuHdlr, StdEdit- 
MenuHdlr and StdFileMenuHdlr. Look at the menu objects 
declared in the “уаг” section, and then look at the the procedures 
“InitApplication” and “MenuChoice” to see how the StdMenu 
unit is used. Notice how clean MenuChoice is because of the 
overridden Choose methods. 


The IconMenu Unit 


The meaty unit, as far as we are concerned, is IconMenu. 
This unitprovides icon menu functionallity as anatural extension 
of the StdMenu facilities. The object type IconMenuHdlr, a 
descendant of MenuHdilr, adds a Setup method which is used to 
define the parameters of the icon menu. That includes what the 
first icon's resource id is (the rest must follow in sequence), how 
many icons you have to display, how many icons wide you want 
the menu, how many extra pixels of blank space you want around 
each icon, and what the name of the menu is. Setup calculates 
how many icons tall the menu needs to be. These parameters are 
then stored in the IconMenuHdlr data record. 

The Create method is in charge of a couple of tricks. Since 
the IconMenu is a non-standard menu, we have to set up our own 
menu definition procedure. My Icon menu definition procedure 
is IconMenuDef, a global procedure in the implementation part 
of the unit. IconMenuDef is installed as the menu's definition 
procedure by the Create method. When the Create method first 
calls NewMenu, it gets a standard Menulnfo record. Since we 
want to store the larger IconMenuInfo record, Create calls 
SetHandleSize to "stretch" the storage block to the required size. 
The call to NewMenu also fills in the menuProc field with a 
handle to the standard menu definition procedure; we want to 
write over that with a handle to our own menu definition proce- 
dure. Be careful! The default menuProc handle that you get 
points to the one and only master pointer to the standard menu 
definition procedure. Assign a new handle to menuProc (which 
gets a new master pointer) before going through menuProc to set 
up a new menu definition. If you don't, you clobber a/] menus. 
I am embarrassed to say I learned that the hard way, although it 
is obvious when you stop and think about it. 

The Create method also sets up a reference in the menu 
record totheIconMenuHdlr object. That way IconMenuDef can 
find its way back to the data telling it what icons to draw where. 
(Inanormal menu, the item information itself is stored following 
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the Menulnfo record.) To set up the object reference, the 
menuHandle is type converted to an IconMenuHandle, and 
SELF is tucked away іп the IconMenuInfo record. SELF is a 
reference to the object calling the method. Each instance of an 
IconMenuHdlr must call Create, and thus each icon menu gets its 
own list of icons and its own height and width. The IconMenu- 
Info record defined in the unit interface provides the necessary 
type information for the Create method to place the object 
reference in the menu data. 


The MDEF Procedure 


MDEF procedures have been described before in MacTutor, 
also reprinted in The Complete MacTutor, Vol. 2, p. 248, 251); 
I will just touch on the basics here. If you need more information, 
dig out those back issues, or see IM Vol. I, p. 362. 

A menu definition procedure must respond to three kinds of 
“messages”, called mSizeMsg, mDrawMsg, and mChooseMsg. 
When the menu manager sends you the mSizeMsg, he wants to 
know how much space your menu takes on the screen. The menu 
manager sends you the mDrawMsg when he wants you to draw 
your menu on the screen; he has already saved the stuff under- 
neath and given you a nice, white drawing space. When you get 
the mChoseMsg you should check the mouse location that you 
are given and do any hiliting and unhiliting necessary to behave 
like a menu. In a nutshell, that's all there is to it; but I will admit 
it took me a while to get all that to work. 

My menu definition procedure has four local procedures. 
One for each menu manager message type, and one that returns 
a rectangle in global coordinates when given the number of a 
menu selection. This structure is borrowed straight from Daryl 
Lovato's MDEF example in the TML Source Code Library. (If 
I can make a small digression at this point, I would like to 
recommend the Source Code Library as a wonderful learning 
tool. Reading and modifying Source Code Library programs has 
taught me a lot about the Mac and its mysteries.) | 

DoSizeMsg and DoChoseMsg are both quite simple. All 
DoSizeMsg has to do is allow room for the necessary number of 
icons, plus the extra blank space in between. DoChoseMsg just 
searches for the icon that the cursor is over, and updates hiliting 
as necessary. 

DoDrawMsgisalittle more interesting, but still quite simple 
because we can make use of the icon support routines in the 
toolbox. This is where laziness really pays off; drawing all my 
circuit models through brute force code would have made this 
routine a nightmare. I suppose it would be good form to pre-load 
the icon resources for the menu, sincea user could potentially end 
up in swap-a-floppy-land the way DoDrawMsg is now imple- 
mented. The Create method could easily preload icon resources, 
or the preload bit could be set with ResEdit. 


Conclusion 


The fanatical user might make some performance improve- 
ments to the IconMenuDef procedure. The item rectangles are 
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calculated now, that could be sped up with look-up techniques. 
The item search itself could be sped up by doing something more 
elegant than a linear search. The icon menu seems quite fast to 
me as it is, however, so I don't plan to fiddle with it. We non- 
fanatics need only zap up a few icons with ResEdit to have 
graphic menus. 


($L TestMenus/Rsrc ) 


program TestMenus; 


uses 

Macintf, StdPo11, StdMenu, IconMenu; 
const 

( Menu IDs ) 


AppleMenuID = 256; 
AboutAlertID = 1000; 
FileMenuID = 257; 
EditMenuID = 258; 
CktMenuID = 259; ( not а resource id } 
FirstCktIcon = 500; 
NumCktIcons = 7; 
IconsWide = 3; 
BfSpace = 3; 


var 
( Instances of Menu Handlers ) 
AppleMenu : AppleMenuHdlr; 
FileMenu : StdFileMenuHdlr; 
EditMenu : StdEditMenuHdlr; 
CktMenu : IconMenuHdlr; 


( Event’ polling variables ) 
TheEvent : EventRecord; 
EventIsForMe : Boolean; 


( 
| DoMenuChoice - do a menu selection 


procedure DoMenuChoice CMenuCode : LongInt); 
begin 
case HiWord(MenuCode) of 
AppleMenuID: AppleMenu.Choose CLoWord(MenuCode )); 
FileMenuID : FileMenu.Choose CLoWord(MenuCode )); 
EditMenuID : EditMenu.Choose CLoWordCMenuCode)); 
CktMenuID: CktMenu.Choose CLoWord(MenuCode)) end; 
HiliteMenu (0) end; 


| PollEvent - check event queue and dispatch event, if anu 


procedure PollEvent; 
var 
TempWindow : WindowPtr; 
begin 
EventIsForMe := GetNextEventCeveryEvent, TheEvent); 
1f EventIsForMe 
then case TheEvent .what of 
mouseDown : case FindWindowCTheEvent . where, TempWindow) of 
inMenuBar: DoMenuChoiceCMenuSelectCTheEvent .where)); 
inSysWindow : SystemClick (TheEvent, TempWindow); 
otherwise ( ignore ) end; 
keyDown : if BitAndCTheEvent .modif iers,CndKey) € Ø 
then DoMenuChoiceCMenuKeyCCHRCB i Апас 
TheEvent . nessage , Char CodeMask 2222; 
otherwise ( ignore ) end end; 


( 
|  InitApplication 
) 
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procedure InitApplication; 
begin 


Done := False; 


( Create the menus ) 


New CAppleMenu); 
AppleMenu.Setup CAboutAlertID); 
AppleMenu.Create CAppleMenuID); 


New (FileMenu); 
FileMenu.Create CFileMenuID); 


New (Edi tMenu); 
EditMenu.Create CEditMenuID); 


New (CktMenu); 


CktMenu.Setup (FirstCktIcon, NumCktIcons, IconsWide, 


BfSpace, ‘Model’); 


CktMenu.Create CCktMenuID); 


DrawMenuBar ; 


InitCursor end; 


( 
| 
) 
b 


Main 


egin 


InitTheMac; 

InitApplication; 

repeat 
SystemTask ; 
PollEvent; 
until done end. 


($А+) ( Interlinear source on compile to 


($R*) ( Range checking } 


unit 


StdPo11; 


INTERFACE 


MacIntf ; 


var 


Done : Boolean; ( program is 811 done ) 


proc 


IMPL 


edure InitTheMac; 


EMENTATION 


procedure InitTheMac; 


beg 


end. 


( 
| 
) 


in 


InitGraf C@ThePort); 
InitFonts; 
InitWindows; 
InitMenus; 

TEInit; 

InitDialogs (NIL) end; 


StdMenu provides standard menu objects. 


unit StdMenu; 


interface 


uses MacIntf, StdPo11; 


const 


asm ) 
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( Standard File menu item numbers } 
NewItem = 1; 

OpenItem = 2; 

CloseItem = 3; 

( —) 

SaveItem - 5; 

SaveAsItem 
RevertItem 


6; 
T: 
PageSetupItem = 9; 
PrintItem - 10; 
(--) 

(мі еп = 12; 


tupe, 
| MenuHd]r is the base object for all menus. 
| The Create method installs the menu at the end of 
| the menu bar. The Choose method should be overridden 
| with code to perform а menu choice. 
MenuHdlr = object 


TheMenu : MenuHendle; 

procedure Create (RsrcID : Integer); 

procedure Choose (Choice : Integer); 
end; 


( 

| | AppleMenuHdir provides all the functionallity of 
| a standard Apple menu. It must be Setup with an 
| alert id for the About.. message before Create is 
| called. 
) 
А 


ppleMenuHdlr = object (MenuHdlr) 

AboutID : Integer; 

procedure Create (RsrcID : Integer); override; 
procedure Choose (Choice : Integer); override; 
procedure Setup (AlertID : Integer); 

end; 


| | StdFileMenuHdir is а minimal File menu. Тһе Choose 
| method can Close DA s and Quit. 


StdF ileMenuHdlr = object (MenuHdlr) 
procedure Choose (Choice : Integer); override; 
end; 


( 
| StdEditMenuHdlr is а minimal Edit menu. Тһе Choose 
| | method supports DA editing. 


StdEditMenuHdlr = object (MenuHdlr) 
procedure Choose (Choice : Integer); override; 
end, 


implementation 


| Generic Menu Handler 


) 
procedure MenuHdlr.Create (RsrcID : Integer); 
begin 
( Read іп а standard menu resource. 
| Remember: Object variables ere Handles! 
|'Self^ is set only 
| es you enter the method, so HLock it if you call апу 
| potential heap-scremblers! ) 
HLockCHandleCSe1f )); 
TheMenu := GetMenu (RsrcID); 
InsertMenu (TheMenu, 0); 
HUnlockCHendleCSelf 2) end; 
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procedure Menutdir.Choose (Choice : Integer); 


begin end; 


( 
Apple Menu Handler 


procedure AppleMenuHdlr.Create (RsrcID : Integer); 


begin 


( Read in the Apple menu stub, and add DA's ) 


HLockCHandleCSelf )); 


TheMenu := GetMenu (RsrcID); 


AddResMenu (TheMenu, 


'DRVR ^); 


InsertMenu (TheMenu, 0); 
HUnlockCHandleCSelf 2) end; 


procedure AppleMenuHdlr.Choose (Choice : Integer); 


var 
AccName : Str255; 
AccNumber : integer; 
begin 


( Post alert or open DA ) 


if Choice = 1 


then AccNumber := Alert CAboutID, NIL) 


else begin 


GetItem CTheMenu, Choice, АссМате); 
AccNumber := OpenDeskAcc CAccNeme) end end; 


procedure AppleMenuHdlr.Setup CAlertID : Integer); 


begin 


AboutID := AlertID end; 


( 
| Standard File Menu 


procedure StdFileMenuHdlr.Choose (Choice : Integer); 


var 
FrontWP : windowPeek; 
begin 
case Choice of 
NewItem : ; 
OpenItem : ; 


Closeltem : begin ( If frontmost window DA, close it. 


FrontWP := windowPeekCfrontWindow); 
if FrontWP* .windowKind < 0 
then CloseDeskAcc(FrontwP* .windowK ind) end; 


Saveltem : ; 
SaveAsItem : ; 
RevertItem : ; 
PageSetupItem : ; 
PrintItem : ; 


QuitItem : Done := true; 
otherwise ( nothing ) end end; 


( 
| Standard Edit menu 


) 
procedure StdEdi tMenuHd] 
var 

Tresh : Boolean; 
begin 


r.Choose CChoice : Integer); 


Trash := SystemEdit CChoice- 12 end; 


end. ( of StdMenu unit ) 
( 
| Icon menu MDEF unit 
| 


unit IconMenu; 


interface 


Creates and manages а menu of Icons. 
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uses 
Macintf, StdPoll, StdMenu; 
tup 


е 
IconMenuHdlr = object (Мепина1г) 


StartIcon, ( The resource ID of first icon ) 
NumIcons, ( How many icons to use CID's in 
sequence) ) 

IconsWide, ( Menu shape... ) 

IconsTall, ( More menu shape. ) 

BufferSpace  ( Extra white pixels around each icon ) 
: Integer; 

Title ( The name of the menu ) 
: Str255; 


procedure Create (RsrcID : Integer); override; 
procedure Setup ( 
Star tIconReq, 
NumIconsReq, 
IconsWideReq, 
BufferSpaceReq 
: Integer; 
TitleReq 
: Str255); end; 
IconMenuPtr = ^IconMenuInfo; 
IconMenuHandle = ^ IconMenuPtr; 


IconMenuInfo = record 
StdStuff : MenuInfo; ( The defeult MenuInfo record ) 


Handler : IconMenuHdlr ( Reference to the above 
handler object ) 
end; 
implementation 


const 


( 
| 
| 
) 
p 


IconSize - 32; ( How big is en icon ) 


IconMenuDef is installed as the MDEF procedure. 
See IM Vol. I, p. 362 


rocedure IconMenuDef ( 


Message : Integer; 
SelectedMenu : IconMenuHandle; 
var MenuRect : Rect; 

HitPt : Point; 


var WhichItem : Integer); 


|  ItemRect - function to find the rectangle ( in global 
| | coordinates) of а given item number. 


function ItemRect ( 
ItemNum : Integer; 
MenuRect : Rect; 
SelectedMenu : IconMenuHandle) : Rect; 


var 
TempRect 
: Rect; 
ItemLess 1, 
ItemSize 
: Integer; 


begin 
( If ItemNum is а real item, then return the ) 
( global coordinates of the item’s rectangle; ) 
( otherwise return empty rect. ) 
16 (ItemNum ›= 1) 
and (ItemNum <= SelectedMenu**.Handler .NumIcons) 
then with SelectedMenu**.Handler do begin 
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ItemLess1 := ItemNum - 1; 
ItemSize :- IconSize + 2 * BufferSpace; 
TempRect.top := (ItemLess! div IconsWide) 
* ItemSize + MenuRect.top; 
TempRect.left := (ItemLess1 mod IconsWide) 
ж ItemSize + MenuRect.left; 
TempRect.bottom := TempRect.top + ItemSize; 
TempRect.right := TempRect.left + ItemSize end 
else begin 
TempRect.top := 0; 
TempRect.left := 0; 
TempRect.bottom := 0; 
TempRect.right := 0 end; 
ItemRect := TempRect end; 


( 
| DoDrewMessage - handle the menu manager Drew command 
procedure DoDrawMessage ( 

SelectedMenu : IconMenuHandle; 

MenuRect : Rect); 


var 
Selection : Integer; ( Current selection ) 
SelRect : Rect;  ( Current selection” Rect ) 
TheIcon : Handle; ( Handle to selection’s Icon ) 


begin 
( Get every icon in the menu and plot it. ) 
HlockCHandleCSelectedMenu2); 
with SelectedMenu^^.Handler do begin 
for Selection := 1 to NunIcons do begin 
SelRect := ItemRect(Selection, MenuRect, Selected- 


Menu); 


InsetRect(Sel]Rect,BufferSpace,BufferSpace); 

TheIcon := GetIcon (StartIcon + Selection - 1); 

PlotIcon (SelRect, TheIcon) end end; 
HUnlock(Handle(SelectedMenu)) end; 


( 
I DoChooseMessage - handle menu manager Choose command 
function DoChooseMessage ( 
SelectedMenu : IconMenuHandle; 
MenuRect : Rect; 
HitPoint : Point; 
OldSelection : Integer) : Integer; 
уаг 
SelRect : Rect; 
Found : boolean; 
Selection : Integer; 
OldSelRect : Rect; 
begin 
Selection := 1; 
Found: false; 
( Find out which item mouse is over, if any. ) 
repeat 
SelRect := ItemRect (Selection, MenuRect, SelectedMenu); 
Found := PtInRect CHitPoint,SelRect); 
1f not Found then Selection := Selection + 1; 
until (Selection > (SelectedMenu**.Handler .NumIcons)) 
or (Found)); 
( Update hiliting as necessary ) 
1f Found 
then begin ( in an item ) 
if (Selection o OldSelection) 
then begin ( in e different item, change hiliting ) 
OldSelRect := ItemRectCOldSelection, 
MenuRect, SelectedMenu); 
InvertRectCOldSelRect?; 
InvertRect(SelRect) end; 
DoChooseMessage :- Selection end 
else begin ( not па item, unhilite old ) 
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OldSelRect := ItemRectCOldSelection, MenuRect, Selected- 
Menu); 
InvertRect (O1dSelRect); 
DoChooseMessage := 0 end end; 


|  DoSizeMessage - handle the menu manager Size command 


procedure DoSizeMessage ( 
var Menu : IconMenuHandle); 

begin 

with Menu^^.Handler do begin 

Menu^^.StdStuff .menuWidth:= IconsWide*CIconSize + 2 * 
Buf ferSpace ); 

Menu** .StdStuff .menuHeight:= IconsTall*CIconSize + 2 * 
Buf ferSpace ) 

end end; 


( 
| IconMenuDef - main 
begin 

case message of 

mSizeMsg : DoSizeMessage (SelectedMenu); 
mDrewMsg : DoDrewMessage (SelectedMenu, MenuRect); 
mChooseMsg : WhichItem := DoChooseMessage ( 
SelectedMenu, MenuRect,HitPt,WhichItem) end end; 


function Min Ca,b : Integer) : Integer; 
begin 

ifa<b 

then Min := а 

else Min := b end; 


procedure IconMenuHdlr.Setup ¢ 
StertIconReq, 
NumIconsReq, 
IconsWideReq, 
Buf ferSpaceReq 
: Integer; 
TitleReq 
‚ $tr255); 
begin 
StertIcon := StertIconReq; 
NumIcons := NumIconsReq; 
IconsWide := IconsWideReq; 
( Calculate IconsTall from NumIcons and IconsWide ) 
IconsTall := NumIcons div IconsWide 
+ Min K(NumIcons mod IconsWide, 1); 
BufferSpace := BufferSpeceReq; 
Title := TitleReq end; 


procedure IconMenuHdIr.Create (RsrcID : Integer); 
( RsrcID isn’t а resource ID in this cese, just а menu id ) 


г 
TrickuHandle : IconMenuHendle; ( Used for type coercion ) 


begin 
HLockCHandleCSelf 22; 
TheMenu := NewMenu (RsrcID, Title); 
( Get а plain menu record ) 


SetHandleSize (Handle(TheMenu), SizeOfCIconMenuInfo2); 
( Stretch it ) 
1f MemError = 0 
then begin 
( Assign the icon MDEF proc ). 
TheMenu^^.menuProc := NewHandle(8); (Important! ) 
TheMenu^^.menuProc^ := @IconMenuDef ; 
( Stuff іп reference to the MenuHandler object ) 
TrickyHandle := IconMenuHandle (TheMenu); 
TrickyHandle**.Handler := SELF; 
( Insert at end of menu ber ) 
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CalcMenuSize (TheMenu); 
InsertMenu CTheMenu, 0) end 


else 
SysBeep (1); 


HUn lock (Handle(Self )) end; 


end. ( of IconMenu unit } 


IPAS$Xfer 


/Globals -4 
TestMenus 
PAS$Library 
macintf 
stdpoll 
stdmenu 
iconmenu 


* IconMenu.R resources 
x 
IconMenu.rsrc 


Type EEIN = STR 


; ;;Ü by convention 
Icons in Menus by David Curtis M9 MacTutor 1988. 


Туре BNDL 


EEIN 0 
ICN® 1 
0 128 
FREF 1 
0 128 


Туре FREF 
128 


д 


APPL 0 ;; local id 0 for icon list 


х — Multifinder — 


Type SIZE = GNRL 
-1 


д 


‚1 
16384 ;; $4000 = bit 14 set 
( 


148000 j; recomended 
.L 
128000  ;; minimum 


Туре ALRT 
,1000 (0) 
60 128 260 368 
100 
4444 


Туре DITL 
,100 (0) 
2 


Button 
133 128 153 188 
OK 


staticText 
60 41 80 159 
About Menu Test 
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Type ICON = GNRL 
‚505 (0) 

‚Н 

0000 0000 0000 0000 0036 0800 0049 2400 
0049 2400 7169 270Е 8900 0111 8Ғ00 0ІҒ1 
8900 0111 7104 410Е 0104 8100 0105 0100 
0ІҒО ҒҒ00 0005 0000 0004 8000 0004 4000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 7000 000Е 
8800 0011 8FFF ҒҒҒ1 8800 0011 7000 000Е 


Туре ICON = GNRL 
‚504 (0) 


.H 

0000 4000 0000 8000 0001 0000 0002 0000 
0004 0000 7008 000Е 8810 0011 8FFF ҒҒҒ1 
8800 0011 7000 000Е 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 4000 0000 8000 
0001 0000 0002 0000 0004 0000 7008 000Е 
8810 0011 8FFF ҒҒҒ1 8800 0011 7000 000Е 


Туре ICON = GNRL 
‚583 (0) 

‚Н 

0000 0000 0000 0000 0000 0000 0000 0000 
0001 0800 7001 100Е 8801 2011 BFFF 3FF1 
8801 2011 7001 100Е 0001 0800 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 7000 BOE 
8800 0011 8FFF ҒҒҒ1 8800 0011 7000 000Е 


Туре ICON = GNRL 
506 (0) 


4 


0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 7000 000Е 8800 0011 BFFF ҒҒҒ1 
8А04 0111 7204 010Е 0204 0100 0104 0100 
0087 0100 0100 8100 0200 8100 0407 OFEO 
0800 8000 0400 8700 0207 0920 0100 8100 
0080 8100 0107 0100 0200 8100 0400 8100 
0807 0100 0404 0100 0204 0100 7204 010Е 
8А04 0111 BFFF ҒҒҒ1 8800 0011 7000 000Е 


Туре ICON = GNRL 
‚501 (0) 

.H 

0000 0000 0000 0000 0000 0000 0000 0000 
0060 8600 7092 490Е 8892 4911 8F92 49F1 
8800 0011 7000 000Е 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 7000 000Е 
8800 0011 8FFF FFF1 8800 0011 7000 000Е 


Туре ICON = GNRL 
‚500 (0) 

‚Н 

0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 7000 000Е 8800 0011 BFFF FFF1 
8800 8011 7000 800Е 0000 8000 0000 Е000 
0000 1000 0000 1000 0000 Е000 0000 1000 
0000 1000 0000 Е000 0000 1000 0000 1000 
0000 Е000 0000 1000 0000 1000 0000 Е000 
0000 1000 0000 1000 0000 Е000 7000 800Е 
8800 8011 8FFF FFF1 8800 0011 7000 000Е 
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Туре ICON = GNRL 
‚502 (0) 
H 


0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 7000 000Е 8800 0011 BFFF FFF1 
8800 8011 7000 800Е 0000 8000 0000 8000 
0000 8000 0000 8000 0007 Ғ000 0000 0000 
0000 0000 0001 С000 0002 А200 0004 9000 
0000 8000 0000 8000 0000 8000 0000 8000 
0000 8000 0000 8000 0000 8000 7000 800Е 
8800 8011 8FFF FFF1 8800 0011 7000 000Е 


Туре МЕМ) 
‚256 (Ø) 
114 
About Test Menus.. 
(-« 


Туре MENU 
‚257 (8) 

File 

(New /N 

(Open 

Close 

(- 

(бауе 

(Save AS... 

(Revert.. 

(- 

(Page Setup.. 

(Pr int... 

(-С 

Quit/Q 


Type MENU 
,258 (0) 

Edit 

Undo 

(-« 

Cut/X 

Copy/C 

Paste/V 

(- 

С1еаг 


Type ICN® = GNRL 
‚ 128 (4) ;; The Appl. Icon 
H 


003ҒҒСй 000400200 00800100 01000080 
0200004 004000020 @9FFFFD0 13ABF568 
23FFFFE 440422082 807Е2081 80423Е81 
807Е208 180002081 80003Ғ81 80002081 
80 1Е208 1800Е3Ғ81 800Е2081 80142081 
80303F8 180602081 40С02082 2 1803Ғ84 
1300208 808003296 04000020 02000040 
0100008 000800100 00400200 003ҒҒС00 
x 

003ҒҒСФ 0001ҒҒЕ00 OOFFFFOO OIFFFFBO 
O3FFFFC GO7FFFFEO OFFFFFFO IFFFFFF8 
SFFFFFF CTFFFFFFE FFFFFFFF FFFFFFFF 
FFFFFFF FFFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFF FFFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFF FFFFFFFFF ТЕЕҒҒЕҒЕ 3FFFFFFC 
IFFFFFF BÜFFFFFFO 0ТЕЕҒҒЕЙ 0ЗҒҒЕРСЙ 
ЙІЕҒЕЕВ 000ЕҒҒҒ00 007ҒҒЕ00 003ҒҒС00 
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Database Corner 
4th Dimension® Externals 


[Todd Carper is a Technical Support Engineer for 4th 
Dimension® and handles all external procedure development. 
He has been there for one year.] 

External Procedures in 4th Dimension® 


4th Dimension is a powerful and sophisticated database for 
the Macintosh. It provides an excellent environment for devel- 
oping custom databases and applications. 4th Dimension allows 
youto quickly generate screens, menus, buttons, scrollable areas, 
and procedures to create a true Macintosh interface without 
starting from scratch. 


4th Dimension's language enables you to avoid pages of 
code and hours of work by accessing the Macintosh ToolBox 
with high level commands. Though the language is very power- 
ful it may not contain all the built-in commands to meet every 
need. For this reason 4th Dimension was designed as an open 
architecture database that can utilize your own commands. 
These commands are called “external procedures", and this 
document will discuss the design and implementation of external 
procedures. 


External procedures enable you to add unlimited functional- 
ity toa4th Dimension database or application. For example, you 
can add sound, pop-up menus, picture buttons, mathematics, or 
telecommunications capabilities. External procedures are exten- 
sions to the 4th Dimension commands that you create like 
XCMDs for HyperCard. Once the procedure is installed, it is part 
of 4th Dimension and can be called just as you call built-in 
commands. 


External procedures can be written in assembly language, or 
any higher level language that compiles to native 68000 code. It 
is very important that the code be stand-alone, in that it does not 
require additional modules to function properly. This article will 
use Pascal programs created with the Apple Macintosh Program- 
mers Workshop (MPW) Pascal. 


Calling the Externals 


When 4th Dimension *calls' the external procedure, it sim- 
ply performs a direct link, Link A6, to the routine and executes 
the supplied code until the code ends, and by nature executes a 
return statement to the calling routine. 


Because the supplied code is being called from within 
another application, you should not try to access any global 
variables, as those are stored off the A5 register and it's contents 
may not be correct for your call. Therefore always declare your 
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variables local. If you need the variables to be used as if they were 
global then define them within a procedure, and have all called 
procedures and functions defined within the procedure defining 
the ‘global’ variables. 


The idea is to make all references relative. This is important 
because when the code is moved into 4th Dimension, the Code 0 
segment is not used. (This is where the Jump table is located). 
Therefore if you have procedures you want to call, they should be 
declared as FORWARD and your top most procedure should be 
the one that ‘runs’ your program. 


Following is an example external procedure. This procedure 
will receive a number, multiply the number by 2, and return the 
result. Because the variable is declared as a var in the procedure 
parameter list, the result can be returned to 4th Dimension. 


Program Ext Doubler; 
Ver DumInt: Integer; 


procedure Doubler(var TheInt: Integer); 
begin 

TheInt:2TheInt*2; 
end; (Doubler) 


Begin 
Doubler(DumInt); (Used for compile only) 
End. (Main Block) 


Following is an example utilizing multiple procedures 
which doesn't take any parameters. It simply assigns the string 
*Hello there" to the global variable Global2. It then beeps once 
for each character in the string. The variables Globall and 
Global2, appear to be global type variables because the proce- 
dures which use them are within the scope of the procedure which 
defines both the variables and the procedure using the variables. 


The main block calls the procedure Caller, (this call is made 
for compiler considerations only.) Caller then calls the proce- 
dure to be executed, HaveGlobals. HaveGlobals was declared as 
FORWARD so that Caller would know that it exists. HaveGlo- 
bals defines the variables to be used by the procedures defined in 
it’s scope. HaveGlobals assigns the string to Global2. It then 
calls First to assign the length of Globall to Global2. Then 
Second is called to have the system beep Globall times. 


Program TestProg; 
Uses Memtypes, QuickDraw, OSIntf; 


procedure HaveGlobals; FORWARD; 
(so Caller knows about the procedure} 
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procedure Caller; 
begin 

HaveGlobals; 
end; 


procedure HaveGlobals; 
var 
Global 1: Integer; 
Global2:str255; 


procedure First; 
begin 

Global 1:=Length(Global2); 
end; (First) 


procedure Second; 
var Count: Integer; 
begin 
For Count:=1 to Global! do Sysbeep(2); 
end; (Second) 


begin (HaveGlobals) 
Global2:=’Hello there’; 
First; 
Second; 

end; (HaveGlobals) 


Begin (Main Block) 
Caller; 
End. (program) 


Creation of External procedures 


Be sure that if your external compiles to more than 1 code 
segment, or if one of the linked modules is placed in it's own 
segment, that you join the segments into 1 complete segment. 
This is important if your application uses the SANE library. 


You can compile to an application and then use the 4D 
External Mover™ to transfer the code segment and to specify the 
parameters. Youcan also compile directly to a Proc.Ext type file 
and specify the parameter list. Then you can use the 4D External 
Mover to copy the already set-up external to the proper Proc.Ext 
file. There will also be an item in the list, (if viewed in the 4D 
External Mover), with the name %ASInit. This item may be 
deleted from the list as it is not needed by the external. 


Here is an example of a MPW linker spec to join the SANE 
code segment with the Main code segment and the method of 
installing directly into a Proc.Ext type file. 


link -w -p MyProg.p.o д 
* (Libreries)"Interface.o д 
* (Libraries)"Runtime.o д 
“(PLibraries}*Paslib.o à 
* (PLibraeries) "SANELib.o д 
-rt '4DEX-15000'9 "Specify resource ID. 
8 Joins segment Main and the Sane libraries into 
8 one. * 
-sg “Main2=Main,SANELib 49 
# Change segment name. ** 
-sn ‘Main2’=’MyProg(&S ;&R)/d 
® Specify the creator and type. 
-c “4DMX* -t “РЕХТ”д 
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-0 MyProg 


*Note: for this external procedure, the Sane libraries are 
needed, therefore, they must exist in the same segment as the 
main code. If your code does not require the Sane libraries then 
this command is not necessary. Be sure to note the case used in 
“ЗАМЕШЬ ” and the space which is between ‘b’ and the quote 
mark. 


**The segment name was changed from Main2 to MyProg, 
the additional parameters, in parens, specify the types of the 
parameters being passed from 4th Dimension. In this example, 
(&S;&R), specifies that a String and a Real are to be passed. 
String first, Real second. Each parameter is preceded by an 
ampersand, ' &'. A semicolon is used to separate each parameter. 


The parameter types are as follows: 


Integer 
LongInt 
Real 
String 
Text 
Date 
Picture 


g Ü — Ç = г ~ 


Following are the Pascal type definitions for Date and Text 
fields. 


Date tupe 
Date4D = record 


day: integer; 
month: integer; 


year : integer; 
end; 


Text type 
TERec4D = record 


length: integer; 


text: CharsHandle; 
end; 


With the release of the 128k ROMS, the restriction of code 
segments being less than 32k has gone away. Because of this, 
your external procedure may be very large. There is one 
important note however; you cannot perform a branch to an 
address which is farther than 32k from where you are branching 
from. The linker will catch this and you will have to put in a 
“stepping stone’ procedure. All these procedures do is call the 
procedure you wanted to call originally. They are located 
between the calling procedure and the procedure to be called and 
are used as stepping stones to get to the proper procedure. 


In this example, we want to call Proc4 from Procl. Procl 
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and Proc3 are very large; such that the distance from the call to 
Proc3 and the location of Proc3 is greater than 32k when 
compiled. To accomplish the call we need to insert a 'stepping 
stone’ procedure after Proc1 called Step. Proc1 calls the proce- 
dure Step. Step then calls Proc3. In this way, the distance 
between calls is less than 32k. 


Program Ext StepStone; 


Uses Memtypes; 


Var 
. (Variable definitions) 


procedure Proc2; Forward; 
procedure Proc3; Forward; 
procedure Step; Forward; 


procedure Proci; 
var 
MyVer :str255; 
begin 
MyVer :» "Hello"; 
(Now we call Step to get to Proc3) 
Step; 
- {Lot’s of Code) 
end; (Proc!) 


procedure Step; 

begin 
(This routine just calls Proc3) 
Proc3; 

end; (Step) 


procedure Proc2; 
begin 

- (Lot’s of code) 
end;  (Proc2) 


procedure Proc3; 

begin 
(Here^s the code we want to use) 
- (Some more code) 

end;  (Proc3) 


Begin (Main Block) 
Proc]; 
End. (Main Block) 


Handles and External procedures 


Whenever storing a data structure, be sure that you are 
accessing it viaa Handle and that you lock the Handle if you want 
to ensure that it is there when you return. 


Be sure to Dispose of all Handles that you have created when 
you have finished with them. If you leave unused handles in 
memory, you could run out of memory at a later point in the 


program. 
Using Pictures in Externals 


When passing Picture variables, to and from external proce- 
dures, be sure to include room for the additional 6 bytes needed 
by 4th Dimension to store the (Horizontal, Vertical) origin of the 
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picture used when it is displayed in an On-Background field, (4 
bytes), and the mode in which the picture is to be displayed, (2 
bytes). For most pictures this means using SetHandleSize to 
increase the allocated space: 


SetHandleSizeCHandle(MyPic), 
GetHandleSizeCHandleCMyPic)2*6) 


* Remember, Pictures can now be greater than 32k in size. 
Therefore the PicSize element of the PicHandle record, may not 
be valid. You should always call GetHandleSize to learn the size 
of the Picture. 


When using externals it is sometimes necessary to save a 
complex data structure or just a handle of a type unknown to 4th 
Dimension. To store types of handle other than PicHandle, you 
can simply use Type Coercion to change the handle to type 
PicHandle and then pass the handle back to 4th Dimension in the 
form of a picture. Do not attempt to display the ‘picture’ as 
strange things will definitely happen. 


Here is an example of storing SND’s in a 4th Dimension 
picture field. This example reads an SND resource from a file and 
returns to 4th Dimension a picture variable containing the SND. 
You can then store the picture (SND) and replay itat a later time 
using PlayPict, (the routine PlayPict follows this one). 
SoundToPict takes 3 parameters, 
SoundToPict(Parm1;Parm2;Parm3). Рапп] is the name of the 
file on disk containing the SND. Parm2 is the name of the SND 
to be retrieved. Parm3 returns a picture variable containing the 
SND. For information about the Resource Manager, see Inside 
Macintosh. 


Program Ext_SoundToPict; 


Uses MemTypes, QuickDraw, OSIntf, 
ToolIntf, PeckIntf, Sound; 


Ver 
DFile, DSound:str255; 
DPict:PicHendle; 


procedure SoundToPict¢ 
ver TheFile, SoundName:str255; 
var MyPict:PicHandle); 


type 
FFSynthHandle = *FFSynthPtr; 


ver 
MySound : FFSynthHandle; 
TheRes: integer; 
MyPtr :Ptr; 
MyFFPtr:FFSynthPtr; 


begin 
MyPict:=Nil; 
TheRes : OpenResF i leCTheF ile); 
MySound : =FFSynthHand1e(Ge tNamedResource 
(*Snd ‘,SoundName)); {Locate SND} 
(Test if the sound was found and read) 
if MySoundO Nil then 
begin 
HlockCHandleCMySound)2; 
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(Copy the Pointer) 
MyP tr :=Ptr(MySound" ); 
(Туре coerce the new Ptr) 
MyFFPtr :=FFSynthPtrCMyPtr); ` 
(Set the playback mode and ratio} 
MyFFPtr* .mode :=FFMode; 
MyFFPtr^.count:-FixRatioC1, 1); 
MyFFPtr* .wavebytes[@] :=0; 
(Type coerce the handle to type} 
(PicHandle) 
MyP ict:-zPichandleCMySound); 
(Lock the picture so we don’t lose it) 
HLock(Handle(MyPict)); 
(Coerce and Copy the pointer} 
MyPict* :=PicPtrCMyPtr); 
(Unlock the Handles before leaving) 
HUnlockCHandleCMySound)); 
Hunlock(CHandleCMgP ict)); 
(Now Detach the Resource since we) 
(have another handle to it.) 
DetachResourceCHandle(MySound)); 
end; (if mysoundONi1) 
CloseResF i leCTheRes); 
end; —(SoundToPict) 


Begin 
soundToPict(DFile, DSound, DPict); 
End. (Main Block} 


This routine is used to play the SND that was stored in a 4th 
Dimension picture field. It takes a 4th Dimension picture 
variable and converts the ‘picture’ to a sound. The sound is then 
played with StartSound. If the passed picture variable does not 
contain information generated by SoundToPict, you will get 
unexpected results. For information about the Sound Driver, see 
Inside Macintosh. 


Program Ext_PlayPict; 


Uses MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, Sound; 


Var 
DPict:PicHandle; 
DFile, DSound: integer; 


procedure PlagPict( 
var Numer, Denom: integer; 
var MyPict:PicHandle); 


type 
FFSynthHandlez^FFSynthPtr; 


var 
MySound:FFSynthHandle; 
MyPtr:Ptr; 
MyFFPtr :FFSynthPtr; 


begin 

(паке sure that we recieved something) 

if MUPictONil then 

begin 
(Coerce the handle) 
MySound : *FFSynthHandleCMgPict?; 
(Lock the sound so we don't lose it) 
HLockCHandleCMySound)); 
(Copy the pointer) 
MuPtr:=Ptr(MuSound 5; 
(Type Coerce the pointer) 
MyFFPtr :=FFSynthP tr CMyPtr2; 
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(Set the playback mode) 

MyFFPtr* . mode :-FFMode; 

(Set the playback count to the) 

(parameters passed. 

MyFFPtr* .count:=FixRatioCNumer, Denom); 

MyFFPtr^.wavebytes[01:20; 

(Play the sound) 

Star tSound(MyPtr, 
GetHandleSizeCHandleCMySound22, 
POINTERC- 122; 

(Unlock the sound so it can be) 

(disposed) 

HUnLock CHand1eCMySound)); 

end; (if MyPictONil) 
end; (PlayPict} 


Begin 
PlayPict(DFile, DSound, DPict); 
End. (Main Block) 


The Grafport and External procedures 


If you change the current Grafport or it's settings, you must 
restore the Grafport to it's original status before returning to 4th 
Dimension. For example, if you were to call an external proce- 
dure that changed the current Grafport to an off-screen port, 
perform some drawing operations, and use CopyBits to copy the 
image to the original Grafport, you must restore the Grafport to 
it's original location before you leave the external procedure. 
Youcannotaccess QuickDraw globals, therefore you must do the 
following to track the current GrafPort: 


(Get the current GrafPort, DO NOT use 
GetPortCOrgPort); 

(Set to the new port) 
SetPortCMyPor t); 


ThePort) 


(Set the port back to it’s original status) 
SetPortCOrgPort); 


Changing the Mac environment 


It is sometimes necessary to modify the settings of certain 
Mac items, such as the Serial Port buffer size. By default the 
buffer size is 64 bytes. Many applications that use the serial ports 
for communication need to have the buffer much larger. The 
buffer size can be modified while in 4th Dimension but you must 
remember to re-assign the buffer to it's original location before 
exiting 4th Dimension or else the new buffer might be cleared by 
another system operation and there would be an erroneous 
pointer to buffer space. 


Here is an example of how to modify the serial port buffers. 
This routine creates a new buffer the size of NbOfBytes for serial 
port access. SetSerialBuf takes 3 parameters, 
SetSerialBuf(Device;BufHandle;BufSize). Where Device con- 
tains the value O or 1 to specify Printer or Modem, respectively. 
BufHandle will return the address of the generated buffer. (Do 
not change this variable after the call, as it is needed to find and 
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dispose of the buffer later.) BufSize specifies the size of the 
buffer in bytes, to be created. BufSize will return the size of the 
buffer actually created. The minimum buffer size is 1024 bytes. 
The maximum buffer size is 32000 bytes. In the case of an error, 
BufSize will return a negative number specifying the Macintosh 
Error Code. For an explanation of Macintosh Error Codes and 
information about the Device Manager, see Inside Macintosh. 


Program Ext. SetSerBuf ; 


Uses MemTypes, QuickDraw, OSIntf , ToolIntf , 
Pack intf ; 

($0+) 

($R-) 

Var 
BufHendle:Handle; 
Pr interOrModem, NbOf Bytes: Integer; 


procedure SetSerBuf( 
ver PrinterOrModem: Integer; 
ver BufHandle:Handle; 
var NbOfBytes: Integer ); 


var Error ,RefNum: Integer; 


begin 
(default buffersize of 1024 bytes) 
if NbOfBytes«1 then NbOfBytes:71024; 
(пах buffer size is 32000) 
if NbOfBytes> 32000 then 
NbOfBytes:232000; 
(generate space for the new buffer) 

Buf Handle:szNewHandleCOrd4CNbOf Bytes 2); 
(Test for Handle allocation error) 
Еггог:-МетЕггог; 
if Еггог=№Егг then 
begin 

(Move Handle out of the way to avoid) 
(fragmentation. } 
MoveHHICBuf Handle); 
(Lock that puppy down) 
HLock(Buf Handle); 
(Set Reference Number accordingly.) 
(0 is Printer, 1 is Modem) 
if PrinterOrModem-0 then 
RefNum:=-8 (Printer) 
else 
RefNum:=-6; (Modem) 
(Веаѕѕідп the serial port buffer) 
Error :=SerSetBuf (Ref Num, Ptr CBuf Handle*^) 
,Ord(Ge tHandleSize(BufHandle))); 
(Test for errors from reassignment) 
if Error o NoErr then 
begin 
(If errors then Беер апа undo what we) 
(have done.) 
Зу$Веер( 10); 
(Assign the error code to NbOfBytes) 
(so thet it is returned) 
NbOfBytes:-Error; 
(Unlock and dispose of buffer) 
HUnLockCBuf Handle); 
DisposHandle(BufHandle); 
end; (if Error o NoErr) 
end (if Еггог-МоЕгг, TRUE) 
else 
begin 
(there was а memory allocation error) 
SysBeep( 10); 
NbOfBytes:sError; 
end; (if Error=NoErr, FALSE) 


BufHandle:sNi!; 


360 


end;  (SetSerBuf) 


Begin 
SetSerBuf (Pr interOrModem, BufHandle, 
NbOfBytes); 
End. (Main Block} 


This routine disposes of the buffer created by SetSerialBuf 
and reassigns the serial port back to it’s default buffer. ClearS- 
erBuf takes two parameters, SetSerBuf(Device; BufHandle). 
Device specifies the printer or modem port and should be the 
same value that was used when SetSerBuf was called. 
BufHandle contains the address to the buffer generated by 
SetSerBuf. 


Program Ext. ClearSerBuf ; 


Uses 
MemTypes, QuickDraw, OSIntf , ToolIntf , 
PackIntf ; 

($0+) 

($8-) 

var 
BufHandle:Handle; 
PrinterOrModem, NbOf Bytes: Integer; 


procedure ClearSerBuf( 
var PrinterOrModem: Integer; 
var BufHandle:Handle); 


var Error,RefNum: Integer; 


begin 
(test for validity of passed Handle} 
if BufHandleONil then 
begin 
(set RefNum according to the port) 
if PrinterOrModem=0 then 


RefNum:=-8 
else 
RefNum:=-6; 


(Disable usage of our buffer) 
Error :=SerSetBuf (RefNum,Ptr(BufHandle” ) 


2 9 
(Test for errors) 
if Error-NoErr then 
begin 
(Unlock and Dispose of the Handle) 
HUnLock(CBuf Handle); 
DisposHandle(BufHandle); 
BufHendle:zNil; 
end (if Error=NoErr, TRUE) 
else 
(Problem encountered) 
SysBeep( 10); (if Еггог=№Егг, FALSE) 
end (if BufHandleONil, TRUE) 
else 
(Non-Valid Handle was passed) 
SysBeep( 10); 
(if BufHandleONil, FALSE) 
end;  (ClearSerBuf) 


Begin 
ClearSerBuf CPrinterOrModem,Buf Handle); 
End. (Main Block) 


External Areas 
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External Areas provide а way for an external procedure to 
take complete control of an area on a 4th Dimension input layout. 
You could, for example, allow the user to draw shapes using 
QuickDraw, implement a full-function word processor, or dis- 
play a picture format that is not supported by 4th Dimension such 
as TIFF. 


You need at least two external procedures to operate an 
external area. One of the external procedures will control the 
activity in the external area. One or more external procedures 
will be used to exchange information with the external area 
procedure. When the 4th Dimension input layout is opened, the 
external area procedure will be called and should create a data 
structure in memory. This data structure will be used by other 
external procedures to ‘talk’ with the external area. In this way 
your 4th Dimension procedure can know whatis happening in the 
external area and it can provide the external area procedure with 
information about other user operations. 


You define an external area on a 4th Dimension layout by 
drawing a variable field and specifying it as an External Area. 
The variable name will be used to store the address of the data 
structure defined in your external area. You enter the name of the 
external area procedure in the format box in the variable defini- 
tion dialog. (The box may be labeled as ‘Not Used'.) The size 
of the variable box on the layout will determine the size and 
location of the rectangle which your external area procedure can 
control. 


Procedures that are to be used as external area procedures 
must be defined as follows: 


procedure МуЕх{Агеа( 
var AreaEvent :EventRecord; 
var AreaRect:Rect; 
var AreaName:str255; 
var АгеаНпа] :MyDataHndl >; 


EventRecord, Rect, and str255 are defined in Inside Macin- 
tosh. 


AreaEvent is used to inform your external area of Macintosh 
events. 


AreaRect contains the current location of your external area 
on the screen. 


AreaName contains the name of the 4th Dimension variable 
on the layout which defines the external area. 


AreaHndl contains is a handle to your data structure defined 
as type MyDataHndl. AreaHndl is used to exchange information 
between your 4th Dimension procedure and your external area 
procedure. 


You can test for the following events via the 
EventRecord.what parameter: 
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InitEvt 16 

DeInitEvt17 

CursorEvt 18 

SelectReq 20 

ActivNote 21 

DeActivNote 22 

NotUsed 23 

NotUsed 24 

ScrollEvt 25 

DrawReq 26 

UpdateEvt predefined in the Toolbox 
MouseDown predefined in the Toolbox 


Event 16 is informing you that your routine has been called 
for the first time and you should create any data structures 
required by your external area. (Define AreaHndl.) 


Event 17 is informing you that your routine is about to be 
removed and you should clean-up and dispose of any data 
structures you created. (Dispose of AreaHndl.) 


Event 18 is informing you that the cursor is over the area 
defined for your external area. 


Event 20 is a request for you to accept all keyboard events. 
If you return the value 101 in the message element, you will 
receive all subsequent keyboard events until the user clicks on 
another item in the input layout. 


Event 21 is sent only if you requested to be selectable when 
you received event 20. The receipt of event 21 means that your 
area has been selected and you should prepare to receive key- 
board events. 


Event 22 is sent only if you requested to be selectable when 
you received event 20. The receipt of event 22 means that your 
area has been deselected and you should not continue testing for 
keyboard events. 


Event 25 is informing you that the window is being scrolled. 
Thisis so you сап update the rectangle coordinates you are using. 
DO NOT update the screen when this event has been received. 
You will receive an UpdateEvt if the screen needs to be updated. 


Event 26 is a request for you to display your picture in the 4th 
Dimension Layout Editor in place of the 175 and O's displayed by 
4th Dimension. If you return the value 102 in the message 
element, 4th Dimension will not draw the area occupied by the 
defined variable associated with the external area procedure. If 
you accept responsibility for drawing the area, then you must 
draw a picture or nothing will be displayed. 


You do not directly pass parameters to an external area 
procedure, rather you access the data structure defined as type 
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MyDataHndl and place information in the data structure for the 
external area to recognize and act upon. 


For example, the following external area procedure detects 
a mouse down event within an external area. When a mouse 
downis detected in the external area, a 1 will be stored in the data 
structure pointed to by AreaHndl. This external area procedure 
is useful for defining invisible buttons on a 4th Dimension input 
layout. 


Program Ext AreaButton; 


Uses MemTypes, QuickDrew, OSIntf, 
ToolIntf, PeckIntf; 


Const 
InitEvt- 16; 
DeInitEvt=17; 


Type 
(This is the definition of the data) 
(structure I want to use. А11 I went) 
(+0 know is if the Mouse was clicked) 


(іп the external area. 0 if NO,) 
(1 if YES.) 
MyData = record 


Status: Integer; 
end; 

MyDataPtr = ^ MyData; 

MyDataHnd] = “MyDataPtr; 


Var 
AreaEv :EventRecord; 
AreaRec:Rect; 
AreaNam:str255; 
AreaHnd : MyDataHnd] ; 


procedure AreaButton( 
ver AreaEvent :EventRecord; 
var AreaRect:Rect; 
ver AreaName:str255; 
var AreaHnd]:MyDateHnd12); 


ver tPoint:Point; (Tracks the mouse location.) 


begin 
Case AreaEvent.What of 
InitEvt: 
begin 
(Create а new handle for our) 
(structure.) 
AreeHnd! :-MyDeteHndlCNewHandlec 
sizeof (MyData))); 
(Initialize the setting to 0. Not) 
(clicked. } 
AreaHnd1** .Status:=0; 
end; (InitEvt) 
MouseDown: 
begin 
(Wait for mouse up so we know they) 
(completed the click within our) 
(area and didn’t drag out of the) 
(erea before releasing.) 
While StillDown do begin end; 
(Is the mouse in our агеа?} 
GetMouseCtPoint); 
(AreaRect is our rect so test if the) 
(point is in our area.) 
if (PtInRect(tPoint, AreaRect)) then 
(They clicked in our area so) 
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(Status=1. Clicked) 
AreaHndl** .Status:=1; 
end; (MouseDown) 
DeInitEvt: 
begin (Get rid of our handle) 


DisposHandleCHandleCAreeHnd12)); 
end; (DeInitEvt) 
end; (Case AreaEvent .What) 
end; (AreeButton) 


Begin 
AreaButtonCAreeEv, AreaRec, АгеаМап, 
AreaHnd); 
End. (Main Block) 


The external area procedure above will track whether a 
mouse down has occurred in the external area. Now we need to 
check it's status from our 4th Dimension procedure. We check 
the status by calling another external procedure which accesses 
the data structure we created and returns the current setting of 
AreaHndl^^,Status. Once we've tested the variable, we set 
AreaHndl^^,Status back to 0, (not clicked), so we can test for the 
next mouse down. 


We check the current setting with the following external 
procedure: 


Program Ext. GetButton; 


Uses MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf; 


Type 
MyData = record 
Status: Integer; 
end; 
MyDatePtr = ^ MyData; 
MyDeteHndl = ^MyDatePtr; 


Var 
Areahnd:MyDataHnd1; 
Result: Integer; 


procedure GetButton( 
ver AreaHndl:MyDateHndl; 
ver Result: Integer); 


begin 
(Result returns Status} 
Result :=AreaHndl]** .Status; 
(Set Status to Not Clicked} 
AreaHndl^*^.Status:20; 

end;  (GetButton) 


Begin | 
GetButtonCAreeHnd, Result); 
End. 


From 4th Dimension we would call this procedure as 
GetButton(MyButton;Clicked). Where MyButton is the name of 
the 4th Dimension variable defining the space for the external 
area. (Remember, the variable name contains the address of the 
data structure in memory.) Clicked is a 4th Dimension global 
variable which will return the current setting of 
AreaHndl^^ Status. 
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When writing and installing external areas it is important to 
note that once you have assigned the external area to a variable 
in the layout editor, the External is called by the layout editor. 
Therefore, it is important that your routine be ready to be called 
immediately. 


4D External Mover 


There are 3 resource types used for 4th Dimension externals 
plus any additional resources required by your external proce- 
dure, They are 4рЕХ, 4DTE, and 4BND. 


4DEX contains the code for your external procedure. Each 
procedure must have only one 4DEX resource. Therefore, if your 
procedure compiles to more than one code segment, you must use 
linker commands to join the code segments. 


4DTE contains the comments about the external procedure. 
The information in 4DTE resources, appear in the comments 
field in 4D External Mover, for the associated 4DEX code. 


4BND contains the bundling information needed by 4D 
External Mover to properly copy your external routines and 
bundled resources to other files. Bundling ensures that when you 
use the 4D External Mover to transfer an external to another file, 
that you get all necessary resources which have been bundled 
with that external procedure. 


When 4D External Mover copies external procedures and 
any associated resources, specified in the bundle, it checks the 
global resource id's of resources currently in the file. If the 
resource id of the external you want to install is already in use, 
then 4D External Mover will change the global id of the resource 
being copied. If the id changes, 4D External Mover will also 
update the bundle information for that external procedure. 
Because the resource id may change when the resource is later 
copied, itis important to not access needed resources directly via 
the global resource id, unless you are sure the id is correct. 
Following is example code for obtaining the global id of re- 
sources which may have moved. This code is from the 4th 
Dimension Utilities and Developers Notes. 


(The CurProcResid function is ет 
(code which returns the 4BND resource 
(number . ) 


function CurProcResid: Integer ; 
INLINE $3EAD, $0Е4Е; 


function GetResNumCT : ResType; 
FORWARD; 


Localid: Integer): Integer; 


. Your code here 


(Pass GetResNum the resource type and) 
(the local id and it will return the) 
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(global id.} 
function GetResNum; 


type 

ResEntry = record 
Typ:ResType; 
LocalNum, GlobalNum: Integer; 
end; 

ResTab = record 
nbEntry: Integer ; 
Tab: аггау[ 1..1] of ResEntry; 
end; 

ResTabPtr = ^ResTab; 

ResTabHandle = “ResTabPtr; 


var 
i: Integer; 
r :ResTebHandle; 
Done :Boolean; 


begin 
GetResNum: 70; 
Done :=False; 
1:21; 
(Get the pointer to 4BND resource) 
r:=POINTERCGetResource( “АВМО”, 
CurProcResId)); 
(make sure we found the resource) 
if ro Nil then 
begin 
(Cycle thru all the entries in the) 
(48ND resource} 
whileCCi«sr^^.nbEntry?) and 
(NotCDone222 do 
begin 
(loop until we find the one with) 
(the localID and the type we want) 
with r^^.Teb[il do 
begin 
(check for & match) 
if (t=Tup) and 
(LocalNumsLocallId) then 
begin 
(we found it, so return the) 
(GlobalID to the calling routine) 
GetResNum:»61obalNum; 


end; (with) 
1:=1+1; 
end; (while) 
end; (if roNil) 
end; (GetResNum) 


(increment our entry counter) 


4th Dimension and external procedures can significantly 
improve your programming efficiency. 4th Dimension can 
fulfill most of your program development and data management 
needs. External procedures can supplement 4th Dimension by 
providing an open architecture and greater flexibility. This 
document provided the information you need to create and install 
external procedures to 4th Dimension. I hope this will help you 
to create externals to make your 4th Dimension databases and 
applications insanely great. 
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Pop-up Menus CDEF Pascal 
Pop-up Menu CDEF. 
Control Definition Function The pop-up menu CDEF described herein extends that 
by James Plamondon standardization to pop-up menus, by making pop-up menus 


[James Plamondon has a BS in Computer Science from the 
University of New Mexico, in addition to a BS and Master's work 
in Geology. He has programmed professionally on the Mac for 
one year, and about two years before. He is currently working at 
Abacus Concepts, makers of StatView.] 

The Challenge 

I like a challenge as much as the next Guy. Like Sir Edmund 
Hillary, I sometimes accept challenges just because they're there. 
But it's always satisfying when I can do some programming 
which is fun for me, and beneficial to my employer as well. 

In Inside Macintosh, Volume Five, on page 242, I found my 
most recent Everest. That page discusses how to use the new 
Toolbox function PopUpMenuSelect(). Near the end of the page 
is the brief notation: “(using PopUpMenuSelectO] could be 
handled by creating a pop-up menu control within the applica- 
tion." 

That sounded useful, so I called Mac Developer Services (оп 
AppleLink) and asked for a copy of the pop-up menu control's 
definition function To my surprise, it didn't exist — or at least, 
they didn't have one. 

There was the challenge. With a pop-up menu Control 
Definition Function (CDEF), pop-up menus could be used as 
easily as radio buttons or scroll bars. The application that I was 
writing for my employer at the time would also make use of pop- 
up menus, so I could even justify the time I spent on it! What a 
deal! 


Why Use a CDEF? 

Have you ever written code to draw a pushbutton — such as 
the OK or Cancel buttons ina dialog? Have youever written code 
to draw a scroll bar, hilite an up-arrow, or draw a thumb region 
being dragged? 

Probably not. All of those operations are performed by 
Apple's standard CDEFs. Because Apple includes these in all of 
its System files, you never have to worry about drawing or 
manipulating these controls. The CDEFs do all of the work, 
without your even paying attention to it. 

What would happen if Apple didn't provide these standard 
CDEFs? Every button would look and feel different. (Did I say 
“look and feel?” Sounds like a lawyer!) Imagine how different 
Mac software would be today if all pushbuttons, radio buttons, 
checkboxes, and scroll bars behaved differently. (And think how 
different MS-Windows would be!) The standardization of such 
controls greatly enhanced the Mac’s ease of use, both for the user 
and the programmer. All this, because of the much-neglected 
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trivial to program, just as buttons and checkboxes are now. Just 
pop the CDEF into your program’s resource fork (or your System 
file), follow a few simple guidelines, and your pop-up menus will 
look as good as — better than! — Apple’s own. 


The Language 
The pop-up menu CDEF was written in MPW Pascal. It is 
about 4K in size, which is pretty big, fora CDEF. It would bealot 
smaller in Assembler; even C would probably produce a smaller 
CDEF. But everybody knows Pascal, and my employer uses 
Pascal, so it’s in Pascal. 


CDEFs 

CDEFs are described in loving detail on pages 328-332 of 
Inside Mac, Volume One. They are code resources of type 
“СОЕР’, which are loaded into memory whenever acontrol using 
the CDEF is created. Like other DEFs (MDEFs, LDEFs, etc.), 
the code resource has a single entry point at its first byte (7.e., no 
jump table). The entry point must be a function with the 
following definition: 


FUNCTION MyControlCvarCode: INTEGER; 
theControl: ControlHandle; 
message: INTEGER; 


param: LONGINT): LONGINT; 


The function and argument names may be changed, of 
course, but their order and type must be as shown here (from IM 
v1 p329). 

It is assumed (although not required) that there will be a 
separate message-handling routine for each message; all My- 
Control() needs to contain is a CASE statement, calling the 
different message-handling routines to handle the different 
messages. That is the organization this CDEF uses. 


CDEF Messages 

There are nine different messages a CDEF may receive, 
numbered 0 to 8. The first three, drawCntl, testCntl, and 
calcCRgns, must be handled by all CDEFs. Whenthe CDEF gets 
a drawCntl message, it needs to draw the control. The “рагат” 
argument will contain the part code of the part that needs to be 
redrawn, or O if the whole control is to be redrawn. You don't 
need to draw anything if the control is invisible (which you can 
determine by looking at the control's contrlVis field). If the 
control is inactive (contrlHilite 2 255), then you need to draw the 
control differently (preferably by ‘greying it out’), to tell the user 
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that it's inactive. 

The testCntl message is sent to find out which part of the 
control (if any) the given pointis in. The ‘given point’ is passed 
іп the ‘рагат’ LONGINT argument, in local coordinates. The 
part code of the control part in which the point lies should be 
returned by MyControl() — or return O if the point is not in the 
control. This is the only message for which the pop-up menu 
CDEF returns a meaningful function result; for all other mes- 
sages, it just returns O. 

The next two CDEF messages, initCntl and dispCntl, need 
only beimplemented by the CDEF if each control handled by the 
CDEF needs to be initialized in some way, and then have its 
initialization voided when the control is disposed of. In this 
CDEF, for example, each control is allocated a memory block 
from the heap to hold color information and a handle to its pop- 


up menu. Thisstorage is deallocated when the control is disposed 
of. 


The next three CDEF messages, posCntl, thumbCntl, and 
dragCntl, need to be implemented only if your control has an 
indicator region (like the thumb of a scroll bar) that can be 
repositioned by the user. The pop-up menu CDEF has no such 
indicator, so when the CDEF receives these messages, it just 
returns without doing anything. 

The last CDEF message, autoTrack, if this CDEF's bread 
and butter. The autoTrack message is sent to the CDEF whenever 
the user clicks inside an active control. The ‘param’ field will 
contain the part code in which the mouse lies. The pop-up menu 
CDEF has only one part — the pop-up menu box, part code 1 — 

so it doesn't even check the part code. It just calls PopUp- 
MenuSelect(), updates the control’s data to reflect the user's 
choice, and redraws the control with the newly-selected item in 
the pop-up box. 

So,the CDEF doesall the work. How, then, can we associate 
a control with this pop-up menu CDEF? By using the proper 
control procID, that's how. 


procIDs 

Which CDEF a control uses is specified by the procID field 
of the control specification, whether in a *CNTL” resource or 
(yuck!) in a NewControl() call. The procID contains both the 
resource ID of the CDEF to use for the control, and also a 
"variation code’ specifying what sub-type of control it is. The 
CDEF's resource ID goes into the high three nibbles of the 
procID, while the variation code goes into the low nibble (a 
nibble is half a byte - really!): 


15 4 5 О 


resource ID code 


Pushbuttons, checkboxes, and radio buttons all use the 
. CDEF with resource ID zero (0). They have variation codes 0, 
1, and 2, respectively. Since the high three nibbles hold 0 (the 
resource ID), the procID for these controls is the same as their 
variation code. 

Scroll bars use CDEF 1, and have variation code 0. The 
resource ID (1) goes into bit 4, zero goes into the low nibble, and 
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voila! you get a procID of 16, just like in the manual (IM v1 
p315). 

Our pop-up menu CDEF has resource ID 3, so the procID 
will be $0030 + x (that's in hex; it's 48 + x in decimal), where ‘x’ 
is the variation code (each hex letter represents a nibble). The 
pop-up menu CDEF doesn't use variation codes, exactly; it uses 
variation code modifiers. This is because I wanted the user to be 
able to mix and match certain features of the CDEF. So, I use 
each of the four bits of the CDEFs variation code nibble as a flag 
for one of these features. The features, their bit positions, and 
their constants are: 


Unused uses Bit 0 mUnused = 1 
Resource list uses Bit 1 mRes - 2 
Check item uses Bit 2 mCheck = 4 
Command keys uses Bit 3 mKey = 8 


Resource Ір----1 
|0000 | 0000|001110000| 


ГЕН 


mKey mCheck mRes mUnused 


With this system, assuming that popMenuProc - $30, you 
can specify a pop-up menu containing a list of resource names 
with the procID popMenuProc + mRes ($32). If you want the 
same pop-up menu, with the current item checked, you would use 
the procID popMenuProc + mRes + mCheck ($36). The standard 
pop-up menu control, without resource names, or checked items, 
would have the procID popMenuProc ($30). 


Basic CDEF 

According to the pop-up menu use guidelines (IM v5 р241- 
242), a pop-up menu should be inserted into the menu list just 
before PopUpMenuSelect() is called, and removed from the list 
right after the function returns. This is a pain in the behind, so I 
don't do it that way. The pop-up menu and it's sub-menus are 
inserted into the menu list when the control is defined, and 
removed when the control is disposed of. The guidelines say I 
can do this, if I really want to; so, I did. 


mUnused 
You can use this variation code modifier for whatever you 
want! 


mRes 
If you want the CDEF to find and install a list of resource 
names in the pop-up menu, you need to add mRes to the procID. 
This makes the CDEF look in the refCon field of the control, 
where it expects to find an OSType (such as ‘FONT’ or 
‘ОКУК’). After initialization, the refCon field is no longer used 
by the CDEF, so you get it back to use it however you want. 


mCheck 
If you want the currently-selected menu item to be checked, 
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add mCheck to the procID. You must also set the check mark of 
the default menu item to the character you want to use as a check 
mark. If the default item is unmarked, a standard “7” mark will 
be used. 


mKey 
mKey is reserved for future expansion. More on that later. 


The Pop-Up Menu CDEF 

The CDEF was written to implement standard, resource 
name list, checked item, and sub-list pop-up menus (and combi- 
nations thereof). If color resources are available, and the CDEF 
is running on a color system, the menus and their controls will be 
displayed in living color. At initialization, the CDEF calls 
SysEnvirons(), and stores the hasColorQD field. Whenever 
drawing is to be done, this Boolean is checked. If true, the colors 
of the current menu and/or menu item are retrieved (from the 
menu color information table) and the control is drawn using 
those colors. Otherwise, you get black and white (sigh). 

Note that a pop-up menu control that uses sub-menus will 
draw the control (menu) title and pop-up box in the mTitle color 
of the currently selected menu (or sub-menu). You can see this 
in the example program in the ‘Root’ menu. The currently- 
selected item will be drawn using that item's colors, which may 
be different for each item in a menu. This is demonstrated in the 
"Thanks To" menu. Make sure that each menu title color has 
good contrast against its window’s content color, or the title will 
be hard to read. 

The CDEF draws the title of the pop-up menu as the control's 
title, left-justified in the control’s boundsRect. The CDEF draws 
the pop-up menu box to the left of the control title. Note that all 
of the examples' pop-up menu titles have an extra blank space at 
the end of the title; this just makes the whole control look better. 

The CDEF tries to make the pop-up box as wide as the menu 
it is controlling. If the menu is wider than the boundsRect will 
allow, then the pop-up box is clipped to the boundsRect. Menu 
items that are too long to fit in the clipped box are themselves 
clipped; an ellipsis is appended to such items to inform the user 
than text is missing. You can see this clipping by selecting 
"Monty "Montana-Unit" Cole' in the "Thanks To" menu. 
Monty'snameis the widest item in the menu, and so it defines the 
width of the menu. Since the contriRect is narrower than the 
menu (see that, when the menu pops up, it covers part of the OK 
button?), itis narrower than Monty'sname, too, so Monty's name 
must be clipped. (Sorry, Monty.) 

With the CDEF, a mouse-click in the pop-up box will always 
be inside the default item (as the guidelines require). The user 
will never click in a pop-up box, just to have the pop-up menu 
appear to the left of the mouse — as might happen if the pop-up 
box were set to some "average" menu width, when the menu 
width might change (as with a font menu). When in doubt as to 
how wide to make the boundsRect, make it wider. Use ResEdit; 
it will call the CDEF to draw the control, and you can drag its 
image around. Neat! 

The only way to make the left edges of pop-up boxes line up 
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with other pop-up boxes is to leave the controls untitled, using 
staticText items as titles. The only way to make the right-hand 
edges of the pop-up boxes line up is to make the boundsRect of 
each of the controls no wider than that required by the narrowest 
control. 


The Example Program 

The example program is a very stripped Mac application. It 
simply initializes all of the usual managers, gets a dialog contain- 
ing two buttons, a static text item, and three pop-up menus, and 
displays it. Notice that no filterProc is passed to ModalDialog(), 
and yet the pop-up menus get drawn, put up their menus where 
selected, and so on. The CDEF is doing all of the work! 

After the example program exits the ModalDialog() loop, it 
simply disposes of the dialog and quits. In a real program, you'd 
get the valuesof the last selection from each pop-up menu control 
by calling GetCtlMax() to get the menuID of the menu from 
which the last selection was made and GetCtlMin()to get the item 
number of the last selection in that menu. 


Using Pop-Up Menu Controls 

To use a pop-up menu control in your program, you need to 
place the CDEF into your application resource file. You should 
also create two resources for each control: a ‘MENU’ resource, 
defining the menu to be popped-up (and further *MENU' re- 
sources for its sub-menus, if any), and а ‘CNTL’ resource, 
defining the pop-up menu control. The pop-up ‘MENU’ re- 
source is exactly like a regular ‘MENU’ resource, and its fields 
are all interpreted in the usual way. (See “Command-Key 
Equivalents" below for one possible exception: the menu title.) 


You can use regular *mctb' resources to color your menus and 
their controls. 


The pop-up menu's “СІМТІ.” resource has the same fields as 
all other “CNTL’ resources, but a number of them are interpreted 
and used differently. We'll go over these fields one at a time. 

BoundsRect: The first field is an array of four integers, 
which define the rectangle bounding the control. If the control is 
to be used in a dialog, be sure to make the control's boundsRect 
agree with the item rect in the dialog item list. Otherwise, 
everything gets confused. 

Value: Thecontrol's initial value must be setto the resource 
ID of the menu to be popped-up. The menu's menuID must 
match its resource ID. 

Visible: Same as always. 

Max: Initially, this field must contain the menuID of the 
menu containing the default item. If the pop-up menu has sub- 
menus, this value may be different from the pop-up menu's 
menuID. After the user has made a selection, this field will 
contain the menuID of the menu from which the item was chosen. 

Min: Initially, this field must contain the item number of the 
default item. After the user has made a selection, this field will 
contain the item number of the chosen item. 

ProcID: As discussed above, the procID field will contain 
popMenuProc plus some combination of mUnused, mRes, and 
mCheck (mKey will be discussed below). 


O The Definitive MacTutor, Vol. 4 


RefCon: If the procID includes the mRes modifier, then this 
field must contain the OSType of the resource to be listed in the 
menu. (See ‘CNTL’ 129 for an example.) 

Title: Surprisingly enough, this is the title of the control. 


There are two other fields of importance. These are fields of 
the ControlRecord allocated from the ‘CNTL’ resource. First is 
the contrIData field, which the CDEF uses to store control- 
specific information. Do not mess around with this field. The 
other field of note, contrlA ction, contains (-1); this means that 
the CDEF has a default action procedure. (See IM v1 p323-324; 
also, v1 р328-332.) 


Command-Key Equivalents 

DO NOT USE COMMAND-KEY EQUIVALENTS IN 
YOUR POP-UP MENUS. They will not be recognized, and will 
only confuse the user. I think I know how to make command-key 
equivalents work in pop-up menu controls, but I didn't try to 
implement the scheme. 

I didn't make command-key equivalents work for a number 
of reasons. First, command-key equivalents don't really fit into 
the user interface, with regard to pop-up menus. Second, the 
implementation would require patching MenuKey() with Get- 
TrapAddress() and SetTrapAddress(). Apple has posted signs all 
over these routines saying "future compatibility not guaranteed." 
Patching them would be like driving the family car beyond the 
“End of County-Maintained Road” sign. Third, it would be a lot 
of work. 

The mKey. variation code modifier has been reserved for the 
hardy soul who ventures to implement them. If you manage to 
make it fly, I'd love to hear from you. You can reach me at 
Abacus Concepts, 1984 Bonita Avenue, Berkeley, CA 94704, 
(415) 540-1949. 


Miscellaneous Notes 

Therearea few other points that need to be mentioned before 
you dive into the code. First, again, the resource ID and menu ID 
of the pop-up menu and each of its sub-menus must match. 

Second, if you use sub-menus, make sure that the default 
menu item is not the parent of a sub-menu. Also, be sure not to 
use circular references in your sub-menus. 

Third, don't specify a ‘сс’ resource for the pop-up menu 
control, because it will just get ignored. The control uses the 
menu color information table to color the control and its menus. 
Use *mctb' resources to color your menus and their controls. 
Note that the pop-up control title is in essence the title of the pop- 
up menu, and is colored accordingly. Also note that the 
window's content color is used instead of the menu bar color for 
the title's background color. 

Just before this article went to press, I added some code to 
. allow the use of this CDEF with menu types other than the stan- 
dard textMenuProc. The code requires that the MDEF defining 
the menu respond to two additional messages: the 
mItemRectMsg (512), and the mDrawItemMsg (513). 

When a MDEF receives a mItemRectMsg, it should return 
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the dimensions the given menu item in the given rectangle, with 
the topLeft pointat (0,0) and the botRight point at (width, height). 

When a MDEF receives a mDrawItemMsg, it should draw 
the given menu item in the given rectangle, clipped or scaled as 
needed. 

I have not tested this code with as many custom MDEFs as 
I would like, but it works fine with those I've tested. It really 
should lock the MDEF before calling it, and restore its lock state 
after the MDEF returns, though. I'll save that for version 2.0 
($300 upgrade!). 
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File: 
Terget: 
Sources: 
Created: 


PopMenus . make 

PopMenus 

PopMenus.p PopMenus.r 

Thursday, April 14, 1988 3:21:49 AM 


PopMenus ff PopMenus.r 
PopMenuCDEF .r 
PopMenuCDEF . CDEF 


Rez -rd PopMenus.r -о PopMenus 


a O 


PopMenus ff  PopMenus.p.o д 
PopMenuCDEF . СОЕҒ 9 
PopMenus.r 
Link PopMenus.p.o 9 
* (Libreries) "Runtime.o 
* (PLibreries)^Paslib.o 
-0 PopMenus 


с © 


PopMenuCDEF .CDEF ff PopMenuCDEF.p.o 
Link -sg PopMenuCDEF 
-rt CDEF=1 
-m MYCONTROL PopMenuCDEF.p.o д 
* (Libraries)"Interface.o д 
* (PLibraries) "Paslib.o д 
-0 PopMenuCDEF . CDEF 


© Qv 


PopMenus.p.o f PopMenus.p 
Pascal PopMenus.p -o PopMenus.p.o 


PopMenuCDEF.p.o Í PopMenuCDEF.p 
Pascal PopMenuCDEF.p -o PopMenuCDEF .p.o 


Н ЯНННННННННННИНЯНННННННННННН 8 


% END OF FILE: PopMenus.make & 
Н ЯЕЯННВНВНННННННЯННННИННЯНННННЯН 8 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЕ ЖЖ ХЕХ $ 


Pop-up Menu Example Program 
XE XCEIOECGICEICICE КЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ) 


PROGRAM PopMenus; 


USES MemTypes, 
Quickdraw, 
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OSIntf, 
ToolIntf, 
Pack Intf ; 


CONST 
muDLOGid = 128; ( DLOG resource ID ) 


Activate = 2; (Activate button ) 
PopMenul = 3; ( popMenu control 1 ) 
PopMenu2 = 4; ( popMenu control 2 } 
PopMenu3 = 5; ( popMenu control З } 
ON = 0; (forHiliteControl } 
OFF = 255; ( for HiliteControl ) 
VAR 
dPtr: DialogPtr; ( our test dialog ) 
itemHit: INTEGER; ( user's choice ) 


state: INTEGER; ( ON or OFF 


(ЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖ 
doHitActivate: Toggles the activation state of the 
popMenu control. А150 toggles the Activate 


button’s title (Activate <=> Deactivate). 
ЖЖЖЖЖЖ ЖЖ ЖЖ AAA AKA AKA AAA KKK )) 


PROCEDURE doHitActivateCdPtr: DialogPtr; 
VAR state: INTEGER); 


VAR 
ik: INTEGER; 
ih: Handle; 
ib: Rect; 
BEGIN 


( get handle to Activate button ) 
GetDItemCdPtr, Activate, ik, ih, ib); 


( toggle state variable апа button title ) 
if (state = ON) then 
begin 
state :- OFF; 
SetCTitleCControlHandleCih2, ‘Activate’); 
end 
else begin 
state := ON; 
SetCTitleCControlHandleCih2, 'Deactivate^); 
end; 


( toggle the popMenu controls’ activation states ) 
GetDItemCdPtr, PopMenul, ik, ih, 10); 
HiliteControlCControlHandleCih2, state); 


GetDItemCdPtr, PopMenu2, ik, ih, ib); 
HiliteControlCControlHandleCih2, state); 


GetDItem(dPtr, PopMenu3, ik, ih, ib); 
HiliteControlCControlHandleCih2, state); 
END; ( doHitActivate } 


(ЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ Е AAA AAA ARES AAAAAAA EEE ХХХ 


Main 
EXXEKKAKAAAKAKAAKAAA К AAA AK ХХХ АХА) 


BEGIN 
{ perform the ritual incantation } 
InitGraf C@thePort); 
InitFonts; 
FlushEventsCeveryEvent, 9); 
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InitWindows; 
InitMenus; 
TEInit; 
InitDialogsCNIL); 
InitCursor; 


( read in the dialog from its resource template ) 
dPtr :- GetNewDialog(myDLOGid, NIL, POINTERC- 122; 


( cycle through ModalDialog() until itemHit = OK ) 
REPEAT 
ModalDialog(NIL, itemHit); 


( if the user hit the activate button, toggle } 
IF CitemHit = Activate) THEN BEGIN 
doHitActivate(dPtr, state); 
END; 
UNTIL itemHit = OK; 


DisposDialog(dPtr); 
END. ( program PopMenus ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


END OF FILE: PopMenus.p 
FX55155X55X553X553X55X5X3XXXXXXX5XXXXXXXXXXX35XXXXXXXXX5) 


/RRRERERERAAAAE RARER ERE RAA AAA SAAR AER ERA EAA AAA AAA KEKE 


Pop-up Menu Example - Resources 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKK/ 


Чіпсінде “Турев.г” 
* include “PopMenuCDEF .r ^ 


/* 1 = use color resources; 0 = don't */ 
8Sdef ine COLOR 1 


/* include the CDEF */ 
data 'COEF^ CpmCDEFResID, “popMenu”) ( 
$$resource(“PopMenuCDEF .CDEF*, ‘CDEF’, 1) 


9 


/* our semple dialog */ 
resource ‘DLOG’ (128) ( 
(40, 70, 170, 440), 
dBoxProc, 
visible, 
побоАмау, 


/* 130 tall, 370 wide */ 


); 


/* the sample dialog/s item list: З pop-up menu ctis */ 
resource 'DITL^ (128) ( 
( /* array DITLerray: 4 elements */ 
/* [1] */ 
(10, 275, 30, 360), 
Button ( 
enabled, 
“ОҚ” 


д 


/ [2] */ 
(40, 275, 60, 360), 
Button ( 
enabled, 
“Deactivate” 


/* [3] */ 
(10, 10, 30, 270), 
Control ( 

enabled, 
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128 
}, 


/* [4] */ 
(40, 10, 60, 270), 
Control ( 

enabled, 

129 


2 


/* [5] */ 
(70, 10, 90, 270), 
Control ( 

enabled, 

130 


2 


/* [6] */ 

(90, 10, 125, 360), 

StaticText ( 
disabled, 
“PopUp Menu Control CDEF example. “ 
“James Plamondon, Abacus Concepts, “ 
#(415) 540-1040.” 


) 
); 


resource ‘CNTIL’ (128) ( 
(10, 10, 30, 270), /* rect: contriRect 


*/ 
128, /* value: menu rsrc ID*/ 
visible, /* vis: standard х/ 
128, /* max: default menuID 
2, /* min: default item 8 
popMenuProc  /* ProcID: 3 x/ 
* mCheck, /* var: Check selection 
0, /* rfCon: for user's use 
“Thanks To: * /* title: standard 
д 
resource ‘MENU’ (128) ( 
128, 
textMenuProc, 
allEnebled, 
enabled, 
“Thanks To: *, 
/* 11 items */ 
“Mark Williams", 
noIcon, noKey, noMark, plain; 
“Mark Bennet”, 
noIcon, поКеу, appleChar, plain; 
“Joseph Daniel’, 
noIcon, поКеу, noMark, plain; 
“Dr. Don Morrison’, 
noIcon, noKey, noMark, plain; 
“Andrew Stone’, 
noIcon, noKey, noMark, plain; 
“Eleanor Plamondon", 
noIcon, noKey, noMark, plain; 
“Bruce Wampler’, 
noIcon, noKey, noMark, plain; 
“Patricia Guffey’, 
noIcon, noKey, noMark, plain; 
“Greta Shaw’, 
noIcon, noKey, noMark, plain; 
“Monty \*Montana-Unit\” Cole’, 
noIcon, noKey, noMark, plain; 
“Dr. Bernard Moret’, 
noIcon, noKey, noMark, plain 
}; 


resource ‘CNTL’ (129) ( 
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*/ 


*/ 
); 


(40, 10, 60, 270), /* rect: contrlRect 


129, /* value: rsrc ID x/ 
visible, /* vis: standard */ 
129, /* max: default menuID 
2, /* min: default item 8 
popMenuProc  /* ProcID: 3 x/ 

+ mRes /* var: add res names */ 

+ mCheck, /* var: Check selection 
‘FONT’, /* rfCon: OSType x/ 
*Fonts: * /* title: standard 


resource 'MENU^ (129) ( 


); 


129, ` 
textMenuProc, 
allEnabled, 
enabled, 

*Fonts: ", 

| /* 0 items */ 


resource 'CNTL^ (130) ( 


х/ 


}; 


(70, 10, 90, 270), /* rect: contrl]Rect 


130, /* value: rsrc ID x/ 
visible, /* vis: standard х/ 
133, /* mex: default menuID 
1, /* min: default item 8 
popMenuProc /* ProcID: 3 x/ 
* mCheck, /* var: Check selection 
0, /* rfCon: for user's use 
“Root: “ /* title: standard 


resource ‘MENU’ (136) ( 


75 


130, 
textMenuProc, 
allEnabled, 
enabled, 
“Root: ”, 
( /* 2 items */ 
“Root Item’, 
noIcon, parent, “\00131*, plain; 
“Root Item2^, 
по[соп, parent, *\00 132°, plain 


) 


resource ‘MENU’ (131) ( 


); 


textMenuProc, 
а11Епа Лед, 
enabled, 


"v 
д 


( /* 2 items */ 
“Sub-1 Item1^, 
noIcon, noKey, noMark, plain; 
*Sub-1 Iten2^, 
noIcon, noKey, noMark, plain; 
*Sub-1 Iten3", 
nolIcon, parent, “00133”, plain 


) 


resource ‘MENU’ (132) ( 


132, 
textMenuProc, 
allEnebled, 
enabled, 


"^ 


(° /*2 items */ 


%/ 
*/ 


*/ 
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) 
); 


“50-2 Itemi’, 


noIcon, noKey, noMark, plain; 


«506-2 Item2’, 


поІсоп, noKey, noMark, plain; 


*Sub-2 Item3 Са very, very, very wide item)”, 


noIcon, noKey, поМагк, plain 


resource 'MENU^ (133) ( 


133, 


textMenuProc, 
allEnabled, 
enabled, 


we 
д 


( 


}; 


/* 2 items */ 
*Sub-3 Iten1^, 


noIcon, поКеу, noMark, plain; 


*Sub-3 Item2’, 


по[соп, noKey, noMark, plain; 


“Sub-3 Item3^, 


vif COLOR 
resource 'mctb^ (128) ( 

(  /* array MCTBArray: 12 elements */ 
/* [1] */ 
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128, 
( 


}, 
128, 
( 


), 
128, 
| 


), 
128, 
( 


noIcon, noKeu, noMark, plain 


0, /* menu 128, title х/ 
/* array: 4 elements */ 
/* (1) */ 


$FFFF, $FFFF, $FFFF 


1, /* menu 128, item 1 х/ 
/* arrau: 4 elements */ 

/* [1] */ 

$FFFF, 0, 0, 

/* (2) */ 

$0040, $FFFF, 0, 

/* [3] */ 

0, 0, 0, 

/* [4] */ 

0, 0, 0, 


2, /* menu 128, item 2 х/ 
/* эггау: 4 elements */ 

/* (1) */ 

$FFFF, 0, Ø, 

/* [2] */ 

$0100, $8000, 0, 

/* [3] */ 

0, 0, 0, 

/* [4] */ 

0, 0, 0, 


3, /* menu 128, item 3 x/ 
/* array: 4 elements */ 

/* (1) */ 

$FFFF, 0, 0, 

/* [2] */ 

$0400, $6000, 0, 

/* (3) */ 

0, 0, 0, 

/* [4] */ 


), 
128, 
( 


), 
128, 
( 


), 
128, 
( 


), 
128, 
( 


); 
128, 
( 


128, 


0, 0, 0, 


4, /* menu 128, item 4 
/* arrau: 4 elements */ 

/* (1] */ 

$FFFF, 0, 0, 

/* [2] */ 

$0800, $4000, 0, 

/* (3) */ 


5, /* menu 128, item 5 
/* arrau: 4 elements */ 

/* [1] */ 

$FFFF, 0, 0, 

/% [2] */ 

$1000, $2000, 0, 

/* [3] */ 


6, /* menu 128, item 6 
/ж array: 4 elements */ 

/* (1) */ 

$FFFF, 0, 0, 

/* [2] */ 

$1800, $1800, 0, 

/* [3] */ 

0, 0, 0, 

/* [4] */ 

0, 0, 0, 


1, /* menu 128, item 7 
/* аггау: 4 elements */ 

/* (1) */ 

$FFFF, 0, 0, 

/* (2) */ 

$2000, $1000, 0, 

/* [3] */ 


0, 0, 0, 
/* (4) */ 
0, 0, 0, 


8, /* menu 128, item 8 
/* errey: 4 elements */ 

/* (1) */ 

$FFFF, 0, 0, 

/* [2] */ 

$4000, $0400, 0, 

/* [3] */ 

0, 0, 0, 

/* [4] */ 

0, 0, 0, 


9, /* menu 128, item 9 
/* erray: 4 elements */ 

/* [1] */ 

$FFFF, 0, Ø, 

/* [2] */ 

$6000, $0200, 0, 

/* [3] */ 

0, 0, 0, 

/* (4] */ 

0, 0, 0, 
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*/ 


+) 


Жу 


*/ 


*/ 


*/ 


28, 10, 


}, 


128, 
( 


) 
); 


/* аггау: 4 elements */ 
/* [1] */ 

$FFFF, 0, 0, 

/* [2] */ 

$8000, $0100, 0, 

/* [3] */ 

0, 0, 0, 

/* [4] */ 

0, 0, 0, 


11, /* menu 128, item 11 */ 


/* аггау: 4 elements */ 
/* (1) */ 

$FFFF, 0, Ø, 

/* [2] */ 

$FFFF, $0040, 0, 

/* [3] */ 

0, 0, 0, 

/* [4] */ 

0, 0, 0, 


resource 'mctb^ (129) ( 
(  /* array MCTBArray: 1 elements */ 
/* (1) */ 


129, 0, 
( 


/* аггау: 4 elements */ 
/* (1) */ 
0, $4000, $4000, 

/ 


/* (21% 
0, 0, 0, 
ж [3] */ 
0, $4000, 0, 
* [4] * 
$FFFF, $FFFF, $FFFF 
) 
); 
resource 'mctb^ (130) ( 
(  /* array MCTBArray: 1 elements */ 
/* (1) */ 
130, 6, 
{  /* array: 4 elements */ 


) 
); 


/* (1) */ 

$0, $4000, $0, 
/* (2) */ 

0, 0, 0, 

/* (3) */ 

0, $4000, 0, 

/% [4) */ 
$4000, 0, $4000 


resource ‘mctb’ (131) ( 
(  /* array МСТВАггау: 1 elements */ 
/* (1) */ 
131, 0, 


( 


/* array: 4 elements */ 
/* [1] */ 

$8000, $8000, $2000, 

/* [2] */ 

$0, $0, $0, 

/% [3] */ 

$0, $0, $2, 

/* [4] */ 

$2000, $2000, $8000 
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/* menu 128, item 19 */ 


) 
); 


resource 'mctb^ (132) ( 
/* errey MCTBArray: 1 elements */ 


) 
E 


/* (11 */ 
1%, 0, 


/* erray: 4 elements */ 


/* (1) */ 

$1000, %С000, $С000, 
/ж (21 */ 

0, 0, 0, 

/* (3) */ 

$4000, $6000, $FFFF, 
/* [4] */ 

$6000, $1000, $1000 


resource 'mctb^ (133) ( 
/* erray МСТВАггау: 1 elements */ 


) 
); 


/* [1] */ 
133, 0, 


(  /* array: 4 elements */ 
/* [1] */ 
$8000, $0, $0, 


$4000, 0, $4000, 
/ [4] */ 
$0, $8000, $0 


resource 'dctb^ (128) ( 


xd 


0, 
( 


); 


data 'ictb^ (128) ( 
(000) 0000: 
(004) 0004: 
(008) 0008: 
(012) 000С: 
(016) 0010: 
(0202 0014: 


/* 


4 


/* array ColorSpec: 3 elements */ 


/* L1] */ 


wContentColor, $FFFF, $FFFF, $FFFF, 


/* (2) */ 


wFremeColor, 0, 0, $FFFF, 


/* [3] */ 


wHiliteColor, $2000, $FFFF, $2000 


(024) 0018: 
(028) 001C: 
(030) 001E: 
(032) 0020: 
(040) 0028: 
(048) 0030: 
(056) 0038: 


(064) 0040: 
(0662 0042: 
(068) 0044: 
(0702 0046: 
(0762 004C: 
(082) 0052: 


*/ $"0040 0018" 
*/ $0040 0018" 
*/ $"0000 0000" 
%/ $^0000 0000" 
%/ $"0000 0000" 
%/ $^800F 0040" 


*/ $"0000 0000" 

*/ $"0000" 

*/ $"0003" 

*/ $"0000 0000 0000 0000" 
*/ $"0001 4000 FFFF 4000" 
*/ $0002 0000 0000 0000" 
х/ $"0003 0000 0000 FFFF^ 


*/ $0054" 
*/ $0200" 
*/ $0009" 
*/ $"FFFF 0000 0000" 
*/ $"FFFF FFFF FFFF^ 
*/ $0001" 
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| уж (084) 0054: %/ $"0647 656E 6576 61" 
endif /% COLOR */ 


/* end of resource file */ 


(YXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXFXX5XX5X5X5XXX3X 
PopMenuIntf .p 
This file contains the Pascal interface for the 
constants used in PopUpCDEF.p, end in апу other 


progrem or unit which uses pop-ups. 
ХХХХХХХЕХЕХХХХХХХХХХХХХХХХХЕХХХХХХХХХХЕХХЕХХАХ ХХХ ХХХ) 


UNIT PopMenuIntf ; 


INTERFACE 

CONST 
( VARIATION CODE MODIFIERS: ) 
mUnused = |; 
"Кез = 2 
mCheck = 4; 
mKey = 8 
( pert codes ) 


inPopUpBox 
titlePart = 2; 


н 
tom 
we 


( MDEF message: get item dimensions ) 
mitemRectMsg = 512; 


( MDEF message: draw item іп rect ) 
mDrewItemMsg = 513; 
IMPLEMENTATION 
END. ( PopMenuIntf ) 


(ЖЖЖЖ 


PopMenuCDEF .p 
This file contains the Pascal source code for the 
routines needed to implement the pop-up menu 
button CDEF described Cin passing) in Inside Mac, 
v5, p242. 
XXEXXEXIZXEXXXXXXEXXXXXEXÉXEXXXXOOOOOEOGEOOROOGEOOR ааа) 


UNIT PopMenuCDEF ; 


INTERFACE 

USES 
($U MemTypes.p ) MemTypes, 
($U QuickDrew.p )  QuickDraw, 
($U OSIntf.p } OSIntf, 
($U ToolIntf.p } Томи, 
($U PopMenuIntf.p ) ^ PopMenuIntf; 


FUNCTION MyControlCvarCode: INTEGER; 
theCnt1: ControlHandle; 
message: INTEGER; 
param: LONGINT): LONGINT; 


IMPLEMENTATION 
CONST 
VISIBLE 
INVISIBLE 
INACTIVE = 
ACTIVE 
DRAW_ALL = 0; 
NOT_IN-CTL = 0; 
L_PIXELS = 
GREY = 16; 
PARENT = $18; 


пын! 
сл 
ol 
`. 
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TYPE 

CtlDateRec = record 
popMenu: MenuHandle; 
menuProcID: INTEGER; 
hasColorQD: Boolean; 
markChar : Char; 
wFgColor: RGBColor ; 
wBgColor: RGBColor,; 
wContColor: RGBColor; 
mTitleColor: RGBColor; 
mBgColor: RGBColor ; 
iNameColor: RGBColor; 
iKeyColor: RGBColor; 

end; 

CtiDatePtr = “CtiDataRec; 

CtlDataHd] = “CtlDataPtr; 


StateRec = record 
savePort: GrafPtr; 
savePen: PenState; 
oldClip: RgnHandle; 
newClip: RgnHendle; 
end; 


(ЖЖЖХЖЖЖЖҖЖЖЕЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖАЖЖЕЖЖЖЖЖЖ 


forwerd declarations 
XXXXXX51XXXXXXXXXXXXXXXXXXXFXXXXXXXKXXXXXXKXXKXXXKXXXKKE) 


PROCEDURE doDrewCOntlCtheCntl: ControlHandle; 
vcLong, param: LONGINT); 
forward; 

FUNCTION doTestCntlCtheCnt]l: ControlHandle; 
param: LONGINT): LONGINT; 
forward; 

PROCEDURE doCalcCRgnsCtheCntl: ControlHandle; 
param: LONGINT); 
forward; 

PROCEDURE doInitOntlCtheCnt]: ControlHendle; 
vcLong: LONGINT); 
forward; 

PROCEDURE doDispOntlCtheCntl: ControlHendle; 
vcLong: LONGINT); 
forward; 

PROCEDURE doAutoTrackCtheCnt1: ControlHandle; 
vcLong, param: LONGINT); 
forward; 


622145533522 222222222222222222222222222222 5. 


MyControl: Main entry point. Call appropriate 


message-hendling routine. 
ЖЖ ЖЖ o d o GE EX Xxx) 


FUNCTION MyControlCvarCode: INTEGER; 
theCnt1: ControlHandle; 
message: INTEGER; 
param: LONGINT): LONGINT; 

VAR 

vcLong: LONGINT; 


BEGIN 
MyControl := 0; 
vcLong := Ord4(varCode); 


CASE message ОҒ 
drewOntl: 
doDrewOntlCtheCnt!, vcLong, param); 
testOntl: 
MyControl := doTestCntlCtheCnt], param); 
calcCRgns: 
doCalcCRgnsCtheCnt], parem); 
initOntl: 
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doInitCntlCtheCnt]!, ус опа); 
dispCnt!: 
doDispOntlCtheCnt]l, усі отд); 
eutoTrack: 
doAutoTrackCtheCnt!, vcLong, param); 
END; (cese) 
END; ( MyControl ) 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 


CallMDEF: Calls the given ProcPtr, passing it the 


given parameters. 
XXXKXXXX1X1XXXX2XX5XXXXX1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) 


PROCEDURE CallMDEF(message: INTEGER; 
theMenu: MenuHandle; 
menuRect: Rect; 
hitPt: Point; 
whichItem: INTEGER; 
MDEFProc: ProcPtr); 

Inline 


$205F, ( move.1 (sp)+, ай; get address of proc) 


$4E90; ( jsr (ай) ; call the proc 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 


GetItemRect: Get the given item’s rectangle. 
ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖЖЖЖЖХ ) 


PROCEDURE GetItemRectCtheCntl: ControlHandle; 
menuID: INTEGER; 
menuItem: INTEGER; 
VAR boxRect: Rect); 


VAR 
hitPt: Point; 
menuHd1 : MenuHandle; 
mDefProc: Handle; 
BEGIN 


SetPtChitPt, Ø, 0); 

menuHdl := GetMHandle(menuID); 
mDefProc := menuHdl^^.menuProc; 
LoadResource(mDef Proc); 


Cal 1MDEF CmI temRectMsg, 
menuHdl, 
boxRect, 
hitPt, 
menultem, 
ProcPtr(mDefProc* 22; 
END; ( GetItemRect } 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ KKK 
DrawMenultem: Draw the given menu item in the 


given rectangle. 
ЖЖ ЖЖ ХК К ЖЖ ЖЖ ЖЖ) 


PROCEDURE DrawMenuItemCtheCnt]: ControlHandle; 
menuID: INTEGER; 
menuItem: INTEGER; 
boxRect: Кес%; 


VAR 
hitPt: Point; 
menuHd1 : MenuHandle; 
mDefProc: Handle; 
BEGIN 


SetPtChitPt, 0, 0); 
menuHdl := GetMHandleCmenuID); 
mDefProc := menuHdl^^.menuProc; 
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LoadResource(mDefProc); 


Cal 1MDEF (mDraw!I temMsg, 
menuHd1, 
boxRect, 
hitPt, 
menuItem, 
ProcPtr(mnDefProc^ 22; 
END; ( DrewMenuItem ) 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ARRAS ORE ЖЖ ЖЖ ЖЖ ЖЖ 


GetContentColor: Get the window’s content color. 
ЖЖ ЖЕ ЗЕ КЕ КККК) 


PROCEDURE GetContentColor(wPtr: WindowPtr; 
VAR contColor: RGBColor); 
VAR 
euxWinHdl: ^ AuxWinHndl; 
winCTeble: — WCTabHandle; 


b. ignore: Boolean; 
t INTEGER; 
BEGIN 


b_ignore := GetAuxWin(wPtr, auxWinHd); 
winCTeble := WCTabHandleCeuxWinHdl^^. 
awCTable); 


i := winCTeble^*^ .ctSize; 


( search for wContentColor ) 
while (сі >= Ø) and (winCTable^^.ctTable[iJ.value 
O wContentColor)) do begin 
i := i - 1; 
end; 


( if we didn’t find it, default to first entry ) 
if Ci < 0) then 
i := Ø; 


contColor := winCTable^^.ctTable[i].rgb; 
END; { GetContentColor ) 


CXoxcooeeocxeoreooorooreoreootorerootorooroeorooeroroooororoe erooooeoorobeocx 
GetMenuColors: Initialize the control” s menu color 


information. ctlData must be locked before calling 


this routine. 
МАМЫ ЖЕ ЖЕ КЖ 222222222222 АКАУ 


PROCEDURE GetMenuColors(theCnt1: ControlHandle; 
ctiData: С{10аїана1); 
VAR 
WhiteRGB: RGBColor; 
BlackRGB: RGBColor; 


mbarPtr : MCEntryPtr; 

titlePtr: MCEntryPtr; 

itemPtr: MCEntryPtr; 
BEGIN 


( default colors } 


WhiteRGB.red := $FFFF; 
WhiteRGB.green := $FFFF; 
WhiteRGB.blue := $FFFF; 
BlackRGB.red :-0; 
BlackRGB.green := 0; 
BlackRGB.blue := Ø; 


with theCnt1^^ do begin 

mbarPtr :- GetMCEntry(@, 0); 

titlePtr := GetMCEntryCcontrlMax, Ø); 

itemPtr :- GetMCEntryCcontrlMax, contr Min); 
end; 
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( get defaults from mbar, or default to B&W ) 
with ctlData^^ do begin 
if C(mbarPtr = NIL) then 
begin 
if CtitlePtr = NIL) then begin 
mTitleColor := BlackRGB; 
mBgColor ‚= WhiteRGB; 
end; 


if CitemPtr = NIL) then begin 
iNameColor := BlackRGB; 
iKeyColor := BlackRGB; 
end; 
end 
else if CtitlePtr = NIL) then begin 
mTitleColor := mbarPtr* .mctRGB 1; 
mBgColor := mbarPtr~.mctRGB2; 


if CitemPtr = NIL) then begin 
iNemeColor :- mbarPtr~ .mctRGB3; 
iKeyColor := mbarPtr^.mctRGB3; 
end; 
end; 


( get colors and defaults from the title entry } 
if CtitlePtr € NIL) then begin 

mTitleColor := titlePtr^.mctRGB1; 

mBgColor := titlePtr^.mctRGB4; 


if CitemPtr = NIL) then begin 
iNameColor := titlePtr^.mctRCB3; 
iKeyColor := titlePtr^.mctRGB3; 
end; 
end; 


( set the item colors ) 
if CitemPtr € NIL) then begin 
iNameColor := itemPtr^.mctRGB2; 
iKeyColor := itemPtr^.mctRGCB3; 
end; 
end; (with ctlData** ) 
( GetMenuColors ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖ ЖЖ ЕЖЕ 


InitColorInfo: Initialize the control’s color information. 
3 oXXOGOREOGOKOOROREG IG IG OO ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ E ) 


PROCEDURE InitColorInfoCtheCnt1: ControlHandle; 


ctlData: CtlDataHd!); 


i: INTEGER; 
wPtr: WindowP tr ; 


BEGIN 


HLockCHandle(ct 1Data)); 


with ctlData** do begin 
wPtr := theCnt1^^.contrlOwner; 


( get the window's content color ) 
GetContentColor(wPtr, wContColor ); 


( save the window’s current fg and bg colors } 
GetForeColor(wFgColor 2; 
GetBackColor (wBgColor 2; 


(дей the menu’s and current item’s colors ) 
GetMenuColorsCtheCntl, ctlData); 
end; 


HUnlockCHandleCctlData2); 
( InitColorInfo ) 
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(ЖЖЖЖ КККК 
GetTitleRect: Get the title of the pop-up menu. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 


PROCEDURE GetTitleRect(theCntl1: ControlHandle; 
VAR titleRect: Rect); 


VAR 
finfo:  FontInfo; 
height: INTEGER; 
BEGIN 


GetFontInfoCf Info); 


with fInfo do begin 
height := ascent + descent + leading; 
end; 


( define the title’s rect ) 
with theCnt1^^ do begin 
SetRectCtitleRect, contriRect. left, 
contr IRect. top, 
contriRect.left + 
StringWidth(contrlTitle), 
contriRect.top + height); 


with titleRect do begin 
if (bottom > contrlRect.bottom - 1) then 
bottom := contrlRect.bottom - 1; 


if (right › contrlRect.right - 1) then 
right := contriRect.right - 1; 
end; (with titleRect ) 
end; (with theCntl^^ ) 
END; ( GetTitleRect ) 


(xoc octo rbooororoororoootorooorooroooerpboceroropborpc eco crc oc ec eexx 


GetBoxRect: Get the box surrounding the pop-up 


box. 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKX) 


PROCEDURE GetBoxRect(theCnt1: ControlHandle; 
VAR boxRect: Rect); 


VAR 
lef tEdge: INTEGER; 
popMenu: MenuHandle; 
f Info: Font Info; 
height: INTEGER; 
menuProcID: INTEGER; 
ct1Data: Ct1DataHd1; 
BEGIN 


ctlData := CtlDataHdlCtheCnt1^^ .contr 10аѓа); 
menuProcID := ctlData^^.menuProcID; 


if CmenuProcID = textMenuProc) then 
begin 
GetFontInfoCf Info); 
with fInfo do begin 
height := ascent + descent + leading; 
end; 


with theCnt1** do begin 


( find the left edge of the pop-up box ) 


lef tEdge := contriRect. left + 
StringWidthCcontrlTitle); 


popMenu := ctlData^^.popMenu; 


( defend against Menu Manager bug ) 
CalcMenuS izeCpopMenu?; 
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( define the pop-up box’s rect ) 
SetRectCboxRect, 
lef tEdge, 
contriRect.top, 
leftEdge * 
popMenu^^.menuWidth * 
2 


contriRect.top + height + 1); 


end; (with theCntl^^ ) 
end ( menuProc = nil ) 
else begin 
GetItemRectCtheCnt], 
theCnt1*^^.contr Max, 
theCnt1*^ .contr Min, 
boxRect); 
end; ( else) 


with theCnt1l^^ do begin 
with boxRect do begin 
if (bottom > contrlRect.bottom - 1) then 
bottom := contriRect.bottom - 1; 


if (right > contrlRect.right - 1) then 
right := contriRect.right - 1; 
end; (with boxRect } 
end; (with theCntl^^ ) 
END; ( GetBoxRect ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


GetCtlRect: Get the box surrounding the pop-up box 
and its title. 
Жл ХХ К К ЖЖ ЖЖ ЖЖ) 


PROCEDURE GetCtlRectCtheCnt1: ControlHandle; 
VAR ctlRect: Rect); 
VAR 
boxRect: Rect; 
titleRect: Весі; 


BEGIN 
GetBoxRect(theCntl, boxRect); 
GetTitleRectCtheCntl, titleRect); 


UnionRect(boxRect, titleRect, ctlRect); 


with ctlRect do begin 
SetRectCctlRect, left, top, 
right * 1, bottom * 1); 
end; 
END; ( GetCtiRect ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 

InstallMenus: Recursive routine to install а menu and 
its sub-menus, if any. It is only called once 
(from doInitOnt1C2). 


ЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ eec eee) 


PROCEDURE InstallMenusCrsrcID: INTEGER); 


VAR 
mh: MenuHandle; 
ni: INTEGER; 
i: INTEGER; 
С. Char; 
BEGIN 


mh := GetMenu(rsrcID); 
InsertMenu(mh, -1); 
ni := CountMItemsCmh); 


( look for parent items ) 
for i := 1 to ni do begin 
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GetItemCmd(mh, i, с); 


(АҒ it’s a parent item, recurse on its child ) 


if (с = CHR(PARENT)) then begin 
GetItemMark(mh, i, с); 
Instal MenusCORDCc2); 
end; 
end; 
END; ( InstallMenus ) 


(ЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
RemoveMenus: Recursive routine to remove а menu 
end its sub-menus, if any. It is only called once 


(from doDispCnt1()). 
ЖЖЖЖ 


PROCEDURE RemoveMenus(menuID: INTEGER); 


VAR 
mh: MenuHand le; 
ni: INTEGER; 
i: INTEGER; 
с: Сһаг; 
BEGIN 
mh := GetMHandleCmenuID?; 
ni := CountMI tems(mh); 


( look for parent items ) 
for i := 1 to ni do begin 
GetItemCmd(mh, i, с); 


( if it’s a parent item, recurse on its child ) 


if (с = CHRCPARENT)) then begin 
GetItemMark(mh, i, с); 
RemoveMenusCORDCc2); 

end; 

end; 


( delete the menu from the menu list ) 
DeleteMenu(menuID); 
Re leaseResource(Handle(mh)); 

END; { RemoveMenus ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


ShrinkString: Маке the given string fit in the given 


box. From a program by Bryan Stearns. 
ЖЖЖЖЖЖ ЖЖ ЖЕ ЖЖ ЖЖ ЖЖ ЖЖ ) 


PROCEDURE ShrinkString(VAR s: Str255; г: Rect); 
VAR 

$-р1х: INTEGER; 

S.len: INTEGER; 

room: INTEGER; 


BEGIN 
( how much room do we have? ) 
room := (r.right - r.left) - L_PIXELS; 


( watch for weirdness ) 
if (room < 0) then begin 
room := 0; 
510] := CHR(0); 
end; 


( get the width of the string ) 
S_pix := StringWidth(s); 


(win it fit? ) 
if (s.pix > room) then begin 
s_len := LENGTH(s); 
room := room - CharWidth(’..’); 


375 


repeat 
8-ріх := s_pix - CharWidth(s[s_len]); 
S len := Ss. len - 1; 

until (CS. pix < room) or (LENGTH(s) = 22); 


s len := s. len + 1; 
slis len] := ^n’; 
s(0] := CHR(s. len); 


end; 
END; ( ShrinkString ) 


(YXXX25XX5X5XXXX5X5XXXXXXXXXXXXXXXXXXXX5XXXXXXXXX5X5X5XXXXX5 


DrawTitle: Draw the title of the pop-up menu control. 
ЖЖЖЖЖЖ ЖК ЖЖ ЖКХ ) 


PROCEDURE DrawTitleCtheCntl: ControlHandle); 
VAR 

titleRect: Rect; 

ctlData: CtlDataHd!; 

finfo:  FontInfo; 

baseline: INTEGER; 


BEGIN 
with theCnt1** do begin 
ctlData := CtlDateHdlCcontr Data); 


( if we need to drew in color, set the colors ) 
with ctlData^^ do begin 
if ChasColorQD) then begin 
if CcontriHilite = titlePart) then 
begin 
RGBForeColorCwContColor ); 
RGBBackColor(mTitleColor); 
end 
else begin 
RGBForeColor(mTitleColor); 
RGBBackColorCwContColor ); 
end; 
end; 
end; 


( get the control’s title box, and erase it ) 
GetTitleRectCtheCntl, titleRect); 
EraseRect(titleRect); 


( get info about the current font } 
GetFontInfoCf Info); 


( define baseline } 
with fInfo do begin 

baseline := contriRect.top + ascent; 
end; 


( move to baseline } 
MoveToCtitleRect.left + 1, baseline); 


{ draw control title (= the pop-up menu's title) ) 
DrawStr ingCcontrlTitle); 


( if we drew in color, restore the colors ) 
with ctlData^^ do begin 
if ChasColorQD) then 
begin 
RGBForeColor(wFgColor); 
RGBBackColor(wBgColor); 
end 
else if (contrlHilite = titlePart) then begin 
InvertRect(titleRect); 
end; 
end; 
end; 


376 


END; ( DrawTitle ) 


(Y2X2XXX5XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXF1FXXXKKE 
DrawDropShadow: Draw the shadow around the 


pop-up box of the pop-up menu control. 
XXXXXXX1XXXXXXXXXXXXXXXXXXF51XX1XXXXXXXXXXXXXXXXXXXXXXXXX) 


PROCEDURE DrawDropShadow( 


{һеСпі1: ControlHandle; 
boxRect: Rect); 
VAR 


ctlData: CtlDataHd]; 


BEGIN 
ctlData := CtlDataHdlCtheCnt1^^ .contr Data); 


( if we need to draw in color, set the colors ) 
with ctlData^^ do begin 
if ChasColorQD) then begin 
RGBForeColor(mTitleColor); 
RGBBackColor(mBgColor ); 
end; ( if ) 
end; ( with ctlData** ) 


with boxRect do begin 
( drew the drop shadow ) 
MoveTo(right, top + 2); 
LineToCright, bottom); 
LineToCleft + 2, bottom); 
end; ( with boxRect } 


( if we drew in color, restore the colors ) 
with ctlData^^ do begin 
if ChasColorQD) then begin 
RGBForeColor(wFgColor); 
RGBBackColor(wBgCo lor); 
end; ( if ) 
end; ( with ctlDate** ) 
END; ( DrawDropShadow } 


(ЖЖЖЖЖЖХЖХЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


DrawPopBox: Draw the pop-up box of the pop-up 


menu control. Also drews drop shadow. 
XXXXXXXXXXX1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX£X1XXXXXKX) 


PROCEDURE DrawPopBox(theCnt]1: ControlHandle; 
vcLong: LONGINT); 


VAR 
boxRect: Rect; 
itemStr: Str255; 
ctlDeta: CtlDataHdl; 
f Info: Font Info; 
baseline: INTEGER; 


menuProcID: INTEGER; 


BEGIN 
ctlData := CtlDataHdlCtheCnt1^^.contr Data); 
menuProcID := ctlData^^.menuProcID; 


if (menuProcID = textMenuProc) then 
begin ( standard textMenuProc ) 
with theCnt1^* do begin 
ctlDeta := Ct'DetaHdlCcontr Data); 
GetBoxRectCtheCnt], boxRect?; 


( erase the box апа shadow ) 
with boxRect do begin 
SetPt(botRight, right + 2, 
bottom * 2); 


EreseRect(boxRect); 
SetPtCbotRight, right - 2, 
bottom - 2); 
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end; (with ) 


( get current selection string ) 

Get ItemCGetMHandleCcontrlMax), 
contrlMin, 
itemStr); 


( make the string fit in the boxRect ) 
Shr inkStr ingCitemStr, boxRect); 


( if color, set the colors ) 
with ctlData** do begin 
if ChasColorQD) then begin 
RGBForeColor(mTitleColor); 
RGBBackColor(mBgColor); 
end; 
end; 


{ frame the box } 
FrameRect(boxRect); 


( get info about the current font } 
GetFontInfoCf Info); 


( define baseline ) 
with fInfo do begin 
baseline := contrlRect.top + 
ascent; 
end; 


( if color, set the colors ) 
with ctlData^^ do begin 
if (hasColorQD) then begin 
RGBForeColor( iNameColor ); 
end; 
end; 


with boxRect do begin 
( drew the string in the popup box ) 
MoveToCleft*L.PIXELS, baseline); 
DrewStringCitemStr); 

end; ( with boxRect ) 


( if color, restore the colors ) 
with ctlData^^ do begin 
if ChasColorQD) then begin 
RGBForeColor(wFgColor); 
RGBBackColor(wBgColor); 
end; 
end; 
end; ( with theCOnt1^^ } 
end 
else begin ( non-standard menuProc } 
GetBoxRectCtheCnt]l, boxRect); 
DrawMenul tem( theCnt1, 
theCnt1**.contr 1Max, 
theCnt1^^.contr Min, 
boxRect); 
end; 


DrawDropShadowCtheCntl, boxRect); 
END; ( DrawPopBox } 


(ЖЖЖЖжЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


DrawDisabled: Invert the pop-up menu control's title. 
ЖЖЖЖЖЖЖЖЖЖАЖЖАЖЖАЖЖЖЖЖАЖЖАЖЖЖЖХЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖХ ) 


PROCEDURE DrawDisebledCtheCnt]: ControlHandle); 
VAR 

дгеуРа{: PatHandle; 

ctlRect: Rect; 
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BEGIN 
( get the grey pattern from the System file ) 
greyPat :=PatHandle(GetResource( ‘PAT °,GREY)); 
PenPat(greyPat**); 
Re leaseResource(Handle(greyPat)); 


( set the pen mode } 
PenMode(patBic); 


GetCtlRectCtheCnt], ctlRect); 
PaintRect(ctlRect); 
END; ( DrawDisabled } 


(ХХХ ХХХ ХХХ ASE ЖЖ AKA Ж 


SaveState: Save the current drawing environment. 
ЖЖ ЖЖ КЖ КЕ КЕ AERA ARAL ERA EKA У 
PROCEDURE SeveSteteCtheCnt1: ControlHandle; 
VAR theState: StateRec); 
VAR 


ctlData: CtlDataHd]; 


BEGIN 
( lock the control handle ) 
HLockCHandleCtheCnt 122; 


with theCnt1^^ do begin 

with theState do begin 
( save current grafPort; set to owner ) 
GetPort(savePort); 
SetPortCcontrl0wner); 

( allocate space for clipping regions ) 
oldClip :- NewRgn; 
newClip := NewRgn; 
( save old clipping region ) 
GetClipColdClip); 
( set newClip region to given rectangle ) 
RectRgn(newClip, contr 1Rect); 
( newClip: intersection of rect and region } 
SectRgnColdClip, newClip, newClip); 
( set grafPorts^ clip region to the result ) 
SetClipCnewClip); 
{ save current pen state; normalize pen ) 
GetPenStateCsavePen); 
PenNorma!; 
( if we have color, get the menu color info ) 
ctlData := CtlDataHdlCcontriData); 
if C(ctlData^^.hasColorQD) then begin 

HLock(Handle(ct1Data)); 
GetMenuColors(theCntl, ctlData); 
HUn lock CHandleCct1Data)); 

end; 

end; (with theState ) 

end; (with theCOnt1^* ) 


( unlock the control handle ) 
HUn lock CHandle( theCnt1)); 
END; ( SaveState } 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


RestoreState: Restore the saved drawing environment. 
ХХХАХХХХХХХХХАХ SER ERA ELAR ЖЖ ЖЖ ЖЖ ЖАЯ) 
PROCEDURE RestoreStaeteCtheCntl: ControlHandle; 
VAR theState: StateRec); 
BEGIN 
with theState do begin 

( restore saved states ) 

SetClipColdClip); 

SetPenStateCsavePen); 

SetPort(savePort); 


( dispose of regions ) 

DisposeRgn(oldClip); 

DisposeRgn(newC1 ip); 
end; (with ) 
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END; ( RestoreState ) 


(ЖЕЖЖЖЖЖЕ ЖЖ ЖЕ ЕК КЕ ЖЕ ХЕ ХЕХ 


doDrawCntl: Draw the pop-up menu box and title. 
ХХХХХХХХХХХХХХХХЖХХХХХХЕХАХХХЕКЕЖЖХХХХХХХХХХХХХХХЕЕХА А) 


PROCEDURE doDrewCntlCtheCntl: ControlHandle; 
vcLong, param: LONGINT); 
VAR 


theState: StateRec; 


BEGIN 

if CtheCntl^^.contrlVis = VISIBLE) then begin 
{ save the current drawing environment } 
SaveState(theCnt], theState); 


( lock the control } 
HLockCHandleCtheCnt12); 


( draw the control ) 
DrewTitleCtheCnt12; 
DrewPopBoxCtheCntl, vcLong); 


( if inactive, grey out the control ) 


if CtheCnt1^^.contr Hii tezINACTIVE) then begin 


DrewDisabledCtheCnt!); 
end; 


( unlock the contro! ) 
HUn lock CHandle¢ theCnt1)); 


{ restore the saved drawing environment } 
RestoreState(theCnt], theState); 
end; ( if VISIBLE } 
END; ( doDrewOnt! ) 


УХУ Ех 


doTestCnt!: Determine іп which part of the control Cif 


anu) the given point Cin ‘param’) lies. 
3:3 X xoxo coe eooeoeeooooobeeepooeoeooeoebooec ЖКХ У 


FUNCTION doTestCOntlCtheCnt]: ControlHendle; 
param: LONGINT): LONGINT; 
VAR 
boxRect: Rect; 


BEGIN 
if CtheCnt1^^.contrlHilite <> INACTIVE) then 
begin ( control is active ) 
GetBoxRectCtheCnt], boxRect); 


if PtInRect(Point(param), boxRect) then 
doTestCnt] := inPopUpBox 


18е 
боТеѕіСпі1 := МОТ ІМ СТЕ; 
end 
else ( control is inactive ) 
doTestCnt! := NOT IN.CTL; 
END; (doTestOnt! ) 


(XXXEREXEXXXXEXXXXXXYEXIXXXXEEXXZXXZEXEXEXEXEXXIXXXEEEEXX 


doCalcCRgns: Calculate the region the control 


occupies in its window. 
XX3XX5XX3XXXXXXXX75XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3) 


PROCEDURE doCelcCRgnsCtheCnt]: ControlHandle; 
param: LONGINT),; 
VAR 
boxRect: Rect; 


BEGIN 
if (BitAnd(param, 980000000) = 380000000) then 


begin { wants indicator region - we have none } 


param := BitAnd(param, $OFFFFFFF); 


378 


Se tEmp tyRgn(RgnHandleCparam )); 
end 
else begin 
parem := BitAnd(param, $OFFFFFFF); 


( set the given region to boxRect } 
GetBoxRect(theCnt1, boxRect); 
RectRgn(RgnHandleCparam), boxRect); 
end; 
END; ( doCalcCRgns } 


(Y22233 5XXXXXXX1X55XX555155X5XX51X111XX5XXXXXXXXXXXXXX 


doInitCntl: Do any initialization required for the given 


control. 
1$299222$999 482232292 2 2$ 2 EOS ЖЖ ЖЖ 222222 У 


PROCEDURE doInitOntlCtheCnt]: ControlHendle; 
vcLong: LONGINT); 


VAR 
popMenu: MenuHand le; 
df 1tMenu: MenuHandle; 
ctlRect: Rect; 
ctlData: CtlDataHd!; 
wor ld: SysEnvRec; 
error: 05Егг; 
narkCher : Char; 


menuProcID: INTEGER; 


BEGI 
( lock the control record down ) 
HLockCHendleCtheCnt!2); 


with theCnt1^^ do begin 
( allocate а relocatable block ) 
ctlData := CtlDataHd] (NewHandle(sizeof ¢ 
CtlDataRec))); 


( is color QuickDrew running? ) 
error := SysEnvironsC1, world); 
ctlData** .hasColorQD := world.hesColorQD; 


( store а handle to the control data } 
contrl1Data := Handle(ctlData); 


( erase the control’s rectangle } 
EraseRect(contr IRect); 


( get a handle to the ‘MENU’ resource ) 
popMenu := MenuHendle( 


GetResource( ‘MENU’, contr1Value)); 


( save the menuProc ID ) 
ctlData**.menuProcID := HiWord( 
Ord4CpopMenu**.menuProc)); 


( load pop-up menu, and its sub-menus ) 
InstallMenusCcontr Value); 
popMenu := GetMHandle(contr1Value); 


( save the pop-up menu’s menu handle ) 
ctlData** .popMenu := popMenu; 


( eppend resource nemes to the menu? ) 
if ((BitAndCvcLong, mRes) = mRes) and 
CcontriRfCon € 022 then begin 
AddResMenu(popMenu, 
OSTypeCcontr IRf Con22; 
end; 
( does the user want to use а check mark? ) 
if (BitAndCvcLong, mCheck)=mCheck) then 
begin 
( get а handle to the default menu ) 
dfltMenu := GetMHendleCcontr Max); 
( get the default menu item’s mark cher ) 
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GetItemMarkCdf ltMenu, 
contrlMin, 
markChar ); 
( if no mark char, default to checkMark ) 
if (markChar = CHRCnoMark)) then begin 
markChar := СНЕ(сһескМагк); 
( set the default item s mark } 
SetItemMarkCdf 1tMenu, 
contr iMin, 
markChar ); 
end; 
( save the default item ) 
ctlData**.markChar := markChar; 
end; 
( if we have color, initialize the color info ) 
if (world.hasColorQD) then begin 
InitColorInfoCtheCntl, ctlData); 


end; 
( flag the default action proc ) 
contrlAction := РОІМТЕВС- 1); 
end; (with theCnt] ) 


( unlock the control record before SetCTitle ) 
HUnlockCHandleCtheCnt12); 
END; (dolnitCnt! ) 


(ЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ eoe 


doDispCntl: Do any de-allocation required Гог the 
given control. 
ЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ К ЖЖ OE OUI ) 
PROCEDURE doDispCntlCtheCnt]: ControlHandle; 
vcLong: LONGINT); 


VAR 
popMenu: MenuHandle; 
ctiData: CtlDetaHd]; 
BEGIN 


ctiDete := CtlDataHdlCtheCnt1^^ .contr Data); 
popMenu := ctlData^^.popMenu; 
( remove the pop-up and its sub-menus ) 
RemoveMenus(CpopMenu^* ^ . menuID); 

END; ( doDispCnt] ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖХЖЖАЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖ 


doAutoTrack: This is the default action procedure Гог 

all controls of this type. TrackControl() will 

place the value inPopBox in contriHilite 

before calling doAutoTrack, so the old 

value will be lost before we cen save it here. 
ЖЖЖЖ ЖЖЖЖ какаа 
PROCEDURE doAutoTrackCtheCnt1: ControlHandle; 

vcLong, param: LONGINT); 


VAR 
popMenu: MenuHandle; 
menuResult: LONGINT; 
menulD: INTEGER; 
menultem: INTEGER; 
boxRect: Rect; 
globalPt: Point; 
default: INTEGER; 
saveTeble: MCTableHandle; 
ctlData: С{1раїана1; 

BEGIN 


( lock control handle before dereferencing ) 
HLockCHandleCtheCnt12); 
with theCnt1** do begin 
( set hiliting to titlePart ) 
contriHilite := titlePart; 
( invert the title rect ) 
DrawTitleCtheCnt1); 
{ деф the pop-up box’s rectangle ) 
GetBoxRectCtheCntl, boxRect); 
( get the topLeft point, and convert to global 
SetPtCglobalPt, boxRect.left, boxRect.top); 
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LocalToGlobal(globalPt); 
( get a handle to the pop-up menu } 
ctiDate := CtlDataHdlCcontriData); 
popMenu `= ct'Data^^ .popMenu; 
( determine the default item ) 
if CcontrlMax = popMenu^^.menuID) then 
default := contr Min 
else 
default := * 
( let the Menu Manager vo іле пага stuff ) 
with globalPt do begin 
menuResult := PopUpMenuSelect( 
popMenu, 
v, h + 1, default); 
end; 


( what menu was the selection made from? ) 
menuID := HiWord(menuResult); 
menuItem := LoWord(menuResult); 
( was а menu selection made? } 
if CCmenuID € Ø) and CCmenuID © contr1Max) 
or (menultem<>contr1IMin))) then begin 
( check the current selection } 
if (BitAnd(vcLong, mCheck) = 
mCheck) then begin 
( unmark previous selection } 
Set I temMark( 
Ge tMHandle(contr Max), 
contrlMin, 
CHRCnoMark )); 
( mark current selection ) 
Set I temMark( 
GetMHandleCmenuID), 
menultem, 
ctlData** .markChar); 
end; ( if mCheck } 
( update the MenuSelect() results ) 
contrlMax := menuID; 
contrlMin := menultem; 
( redraw the pop-up box ) 
DrawPopBoxCtheCnt], vcLong); 
end; (if selection made ) 
end; (with ) 


( unlock contro! handle before returning ) 
HUn lock CHandle( theCnt1)); 
END; ( doAutoTrack ) 


END. ( PopMenuCDEF .p ) 


/S53X35XXXXXXXXXXXXXXXXXXXXXXXFXXXXXXXXXXXXXXXXXXXXXXXXX 


Pop-up Menu Control “Rez” File Constants 

‘include’ this file іп any Rez source file that uses 
pop-up menu controls. 

ЖЖ ХЕХ УК КЕ AERA AERA ERA ER К Ех / 

/* standard pop-up menu control procID — */ 

"def ine popMenuProc 48 /* #48 dec, $30 hex x/ 

/* CDEF’s resource ID*/ 


def ine pmCDEFResID 3 

/% VARIATION CODE MODIFIERS: */ 

define mUnused | /* allow sub-menus х/ 
define mRes 2 /% add res names x/ 
"define mCheck 4 /* check menu item х/ 
define mKey 8  /* reserved */ 

/* parent of а sub-menu * / 

define parent “\$ 1B" 

/* MARK CHARACTERS */ 

"define cmdChar НІ”  /* command mark х / 
"define сһескСһаг "41299 /* check mark */ 

8def ine diamondChar  "M$13^  /х diamond mark */ 
“define appleChar “\$14" /* apple mark х / 
/®*Ж®Ж®ХЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖХЖЖАЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖЖ -— 
END OF FILE: PopMenusCDEF .r Sol 


EXEXEXEXXXXXXXXEYXEXEXEEXEEXEXXXXEIEXrfrrxxXrrrirrrkrrkrrrri/ 


Pascal Procedures 
Fun With Regions, Part II 


In our previous paper (Fun with Regions Part I: High Level 
Language Implementation), we showed how it was possible to 
estimate the area of an arbitrarily drawn region from high level 
languages such as Pascal and C using repeated application of the 
ROM subroutine, PtInRgn. Although this approach is simple and 
intuitive, execution time is excessive for large or complex 
regions. Whenever part of a high level language routine con- 
sumes an inconveniently long execution time, the possibility of 
using assembly language to achieve better efficiency should be 
considered. Two fundamental approaches may be applied. A 
study of the code generated by the compiler may reveal unnec- 
essary looping, inefficient use of registers or other complexities 
which can be streamlined. If savings can be made within loops 
executed many times, the resulting speedup can be significant. 
The second approach applies when the task at hand is relatively 
simple and straightforward. In this case, determination of a 
specific efficient algorithm is the key, with translation to assem- 
bly code following directly. In dealing with the area computation 
part of our regions manipulation, we have explored both of these 
approaches and found the latter approach to be clearly superior. 

In the first article, we provided the C Language code for the 
area calculation program at the end of the article with major 
subroutines interpolated into the text as implemented in Pascal. 
In this installment, the *tables are turned"; the interpolated 
routines are implemented for the Megamax C development 
system and the Consulair (MDS) assembly language system 
[This is included in the source code due to space considerations- 
ED]. At the end of the article, a program using the most useful 
of the assembly language optimizations is shown for Turbo 
Pascal with explanation of minor changes needed for the TML 
Pascal Development system. We recognize that our program 
may not be the most elegant or efficient approach to the prob- 
lems; but even where an attempt at optimization yielded poor or 
marginal results, an interesting and - hopefully - useful technique 
is explored. 

Several authors ( Morton, M.: Reduce Your Time in the 
Traps! MacTutor October 1986 pp 21-24. and Knaster, S.: "How 
to Write Macintosh Software." Hayden, Hasbrouck Heights NJ, 
1986, p 368 ) have advocated bypassing the trap dispatcher as a 
means of speeding routines in which ROM calls are made 
repeatedly. Certainly our CountPix routine, since it calls 
PunRgn for every point within the region bounding box, is a 
candidate for this type of optimization. Mike Morton presents the 
underlying mechanism for this strategy, points out some cautions 
and pitfalls апа shows how to do this task in Pascal using 
INLINE calls. Briefly, any call to the ROM must go through an 
intermediate step of finding the “true” address of the call in the 
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particular version of the ROM in your machine before it can be 
invoked. WhenaROM callis to be used many times, this address 
may be determined one time by means of the GetTrapAddress 
function early in the program; then you may employ some means 
of jumping to this address directly whenever the particular ROM 
call is to be used. In C language, the address might be acquired 
as follows: 


trap = gettrapaddress(Oxa8e8); /* trap is a global long integer */ 
/* ASES is the trap # for ptinrgn */ 


In order to see how the jump might be made, consider the 
following “glue” routine which is used for ptinrgn by the 
Megamax system: 


boolean ptinrgn(pt, гоп) /* as copied from qdi3.c */ 
point *pt; 
s rgn; 


asm ( 
subq 82,А7 
result */ 
поуе.1 pt(A62,A0 /* address of point into Аб */ 
тоуе.1 (A02,-(A7) /% dereference and put onto 
stack*/ 
поуе.1 rgn(A6),-CA7)/* region handle onto stack */ 
dc.w 8xa8e8 /* call the ROM for ptinrgn */ 
move.b CA72*,D0 /* result into DØ where C expects to 
find the answer */ 
5. 00 /* sign extend the result */ 


) 


/* make room on the stack for the 


Note that with Megamax inline assembly, the compiler takes 
care of setting up (and tearing down) the stack frame. Automatic 
(local) variables are accessed using the name of the variable as a 
displacement from A6. Global variables are treated similarly as 
offsets from A4. Thus if we have safely installed the true ROM 
address of ptinrgn in "trap", we can write a "new improved" 
version of the glue routine as follows: 


boolean zptinrgn(pt, гоп) 


/ 


/* bypasses the trap dispatcher 


rgnhandle гоп, 


asm { 
subq 82,А7 
result */ 
тоуе.1 pt(A62,A0 /* address of point into А0%/ 
поме.1 (А0),-(АТ7) /* dereference and put onto stack */ 
поуе.1 rgnCA62,-CA7)  /* region handle onto stack */ 
тоуе.1 trapCA4),A2 /% address of “true address” of 
ptinrgn into A2 */ 
jer (42) /* dereference once end jump there */ 


/* meke room on the stack for the 
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move.b (А72%,00 
find the answer */ 
ext.w 00 

) 


/* result into DO where C expects to 


/* sign extend the result */ 


When this version was used in place of ptinrgn, the time 
needed to estimate the area of a region was decreased by 15% for 
small simple regions and about 9% for larger and more complex 
ones. Although this would ordinarily be considered a significant 
improvement, it is little comfort to know that a five minute 
computation can now be completed in only four and a quarter 
minutes. 

Upon examination of the disassembled code for 
counbtpix(), we noticed that the most often used variables were 
the points delimiting the region bounding box as well as the 
"exploring" point on which we called ptinrgn. Following classi- 
cal optimization strategy, the next step was to set up these data 
structures on registers rather than to fetch them every time the 
coordinates of the exploring point were ingremented. The code 
for this implementation of the countpix function is shown below: 


bcountpixCtheregion)/* sets up test point on registers */ 
Шы theregion; 


esn( 

move.] (гар(А4),А2 ; address of ptinregn 

move.w  #0хАВЕВ, DØ ; trap number for ptinrgn 

dc.w бхА 146 ; call the (гар, address is in Аб 

поуе. 1 А0,А2 ; put it into А2 

move.|  theregionCA60,A3 ; regionhandle 

move.] САЗ), ; dereference once 

move.1 — 2CA12,D4 ; topleft of rgnbox 

поуе.1  6(A12,05 ; botright of rgnbox 

move.1 04,06 ; copy of TL es VH current point 
hortest: 

cmp.w D5,D6 ; compare horizontal 

blt.s vertest ; go on 

swap D4 ; 04 is now HV 

eddq.w 81,04 ; down 1 row 

Swap D4 ; пом 04 is back to.HV 

поуе.1 04,06 ; маке this the current test point 
vertest: 

swap D6 ; пом is HV 

swap D5 ; пом is RB 

стр.м 05,06 ; compare vertical 

blt.s pointest ; go on 

bre.s (опе ; 
pointest: 

swap D5 ; back to BR 

swap D6 ; back to VH 

ѕира 82, A7 ; маке room for result 

тоуе.1 06,-CA7) ; point onto stack 

move.] theregion(A6),-CA7) ; rgnhandle onto stack 

jer (А2) ; go to ROM 

move.b (АТ)%,00 ; result onto stack 

tst.b 00 ; wes it true? 

beq skip ; not this time 

eddq.1 %1,питріх(А4); yes, increment the counter 
skip: 

addq.w 81,06 ; over 1 column 
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bra.s hortest 


; back for another point 


done : 


) 


As with the previous attempt at optimization, the speed 
increase with this approach was marginal at best. Our final 
attempt in this direction was to examine the code for ptinregn in 
the ROM in order to transpose (plagiarize?) it directly into the 
above routine. The result was surprising as well as disappointing. 
Although there was a measurable but tiny improvement for small 
simple regions, ones for which optimization was not needed 
anyway, the time needed to calculate the area of large, complex 
or disjoint regions increased significantly!! Our theory as to why 
this happens is based on the way in which the 68000 accesses 
ROM and RAM. Accesses to RAM (where the program resides) 
are shared with the video display, sound generator and disk speed 
controller. This leads to a RAM access rate of approximately six 


Pull parameters off 


ENTER 
faise. 


stack, set tes? to 


eginning oç "region 


в 
. @rouwing instructions” 


increment and check next 
word against vertical (v) 
Component of test point 


No < 


Increment and check next 
word against $7FFF. 


check same word against 
horizontal 00) component 
of test p 


Figure 1. Flowchart of PtinRgn (AON version) 
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megahertz. The ROM has a “direct line" and is accessed at 7.83 
MHz (Inside Macintosh. III-18, Addison-Wesley, Reading MA, 
1985). 

Allof this preoccupation with ptinregn led to an understand- 
ing of why the area computation takes so long for large or 
complex regions. А flow chart of how ptinregn works is shown 
in figure 1. Unless the region under examination is rectangular, 
it may be necessary to examine all of the region data, one word 
at a time, before deciding whether the point is indeed in the 
region. This is particularly true as the exploring point moves 
toward increasing values in the vertical (y) component. Clearly, 
our original countpix procedure, which calls ptinregn on every 
point in the bounding box, covers the same ground many times. 
Based on a conviction that the region information should be 
adequate to permit estimation of the area with one pass, we 
resolved to implement a specific algorithm "from the ground 
up." 

As mentioned in the first installment of this article, region 
information is stored in memory in a way designed to require 
minimalspace. A clearunderstanding of this method of encoding 
region boundaries is necessary in order to design our area 
calculating algorithm. To illustrate this process, consider the 
simpleregion plotted in Figure 2. The numbers on the plot are the 
coordinates of the “corners” of the outlined region. A memory 
dump of the data representing this region is shown below the 
graph. In order to design an algorithm for area calculation, we 
must understand the method of encoding the region in memory. 
As explained in our previous paper, the first five words of this 
data list are the data size in bytes (44) followed by the “upper left" 
and “lower right" coordinates of the rectangular boundary of the 
region - the regnbbox (100,100,220,200). Following these five 
words we find the information needed to compute area. Only 
horizontal boundary information is stored. The region being 
defined consists of the (rectangular) area under a given boundary 
line, extending down to the next horizontal boundary line en- 
countered. Horizontal boundary lines are indicated by a y 
coordinate word, followed by start and stop x values (more than 
one pair if the line has multiple segments). The flag word, #7FFF, 
marks the end of the boundary segments at a particular y value. 
Therefore, the sixth word of data (100) is the y coordinate of the 
top boundary line of the region. It is followed by x values 100 
(start of line) and 200 (end of line). Then we get a flag indicating 
that no more boundary segments exist at this level. The next 
horizontal boundary is the line from (125,150) to (180,150). 
R 


$29,190 190,180 


ЕЕ Fun with Regions || EE 
Here are the first 400 words of the ion data. CFLAG = 32767) 


44 100 100 220 200 100 100 FLAG 150 125 180 FLAG 170 100 125 
FLAG 220 160 200 FLAG FLAG 


Figure 2. “Example” region along with a screenduap of the 
region data. 
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Therefore we find 150 (y value) and 125,180 (x start and stop 
values) to be the next three words of the data. In this manner, the 
remaining data can be seen to define the region of figure 2. The 
double flag indicates the end of the data table. 

The question now is how touse this table to calculate the area 
of the region thus defined. The arrangement of the data suggests 
dividing the area into rectangular pieces and adding their areas. 
We might start by subtracting the first x value (100) from the 
second (200) to get the width of the top of the first rectangle 
(marked “А”). The у value of this line could be put aside to be 
subtracted from the next y value (170) yielding the height of the 
rectangle. The product of these dimensions is one component of 
the final area 

The x values following the 150 are endpoints of a new 
horizontal boundary line. Since this line falls under the previous 
boundary, it represents the bottom of a rectangular piece rather 
than the top of a new one. From here (y = 150 ) our region will 
now grow downward in two rectangular pieces, B and C. To 
calculate the areas of these pieces, we must make use of the two 
new x values found in the data table (125,180). If we arrange all 
x values found so far in order of magnitude (100, 125, 180, 200), 
the appropriate widths can be found by pairing the values and 
subtracting the first from the second in each pair. This is a rule 
we can use in our algorithm: maintain an ordered list of all 
encountered x values, pair them and subtract the first of each pair 
from the second. The sum of these differences will be the total 
width at the top of each of the rectangular regions. The y 
coordinate at the top of B and C is subtracted from the next y 
coordinate found (170-150) to determine the height of these 
rectangles. Height times width is then added to the accumulating 
total area. 

One problem remains: how to end the process? Following 
y value 170, we find x values of 100 and 125 in the data. One leg 
of our descending area ends here so we would like our x table to 
list just 180, 200 (the top of D) from here on. Therefore, the final 
rule we need for our area algorithm is to remove entries from the 
x value ordered list whenever they are matched by a newly 
encountered x value. At the final y value (220), we subtract the 
remaining x pair (200-180), and multiply by the last y difference 
(220-170), giving the area of the last piece, D. 

A flowchart of this process is given in figure 3. The routine 
as implemented to provide a linkable object file using the MDS 
(now Consulair) 68000 assembly system is shown below. Using 
the TTAA (Tom Terrific Area Algorithm), even the largest and 
most complex region that could be drawn on the Macintosh 
screen could have its area estimated in less than 20 seconds. Such 
regions take as long as ten minutes using the old CountPix. 

This is the code for use with the MDS assembler to produce 
the file ACountPix.REL. This can then be linked to a Pascal or 
other “main” program. 


; ACountP ix.asm 

; Pascal Usage: Function ACountPixC theRegion:RgnHandle) 
LongInt; 

; This function emulates CountP ix 

; Written by Thomas W. Moore, Ph.D. and Stephen Dubin, V.M.D., 
Ph.D. | 
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поуеа.1 


сіг.1 
lea 
Initialize area to 0: РО 
А = О. Yold = 0. А 
Set pointer to 6th. data 52 
word. ( 1st. y value) ROVE K 
move.w 
move .w 
Read u value from data. move.w 
Sub.w 
sub.w 
Subtract previous y value to get height: mulu.w 
(Ynew - Yold -» H) move.w 
bra 
From present list of x velues, form sum of morework : 
differences to get width: lea 
(2nd - 1st and 4th - 3rd, etc. -» W) clr.1 
If list is empty, W=0. сіг.1 
move.1 
Multiply height by width and add to area: d 
A = À + HIW омеа. 
movea. | 
move .w 
Read in “prospective” x 
value 
gety: 
move .и 
jsr 
Read in another value 
getx: 
move .w 
cmpi.w 
It is an x value. For each x value: If its bne 
value is already in the ordered list, discard nove.w 
and remove it from the list. Otherwise, стр " 
insert the new value in its proper place. beq | 
bra 
movea. | 
cmp .w 
Figure 3. Flowchart of "Топ Teriffic" Area Algorithm bis 
; Copyright € 1987 
addq 
XDEF ACountPix . bra 
XREF myBUF 
; The buffer is allocated in the calling program even though it | $1: 
might be lea 
; more elegant to allocate it here with a DS statement; however 
Turbo bgt.s 
; Pascal V1.8 seems intolerant of this. Ср 335 of the Turbo Pascal 
manual ) 
3 ~ INCLUDES mkroom: 
Include Traps.D ; Use System and ToolBox traps move .wW 
Include ToolEqu.D ; Use ToolBox equates cmp.w 
beq.s 
bcc.s 
стра.1 
ACountP ix: bne 
link А6,80 ; Set up frame pointer 
помет. Т. А0-АЗ/00-07,-(АТ) ; save the world insert: 
сіг.1 -CAT) ; маке room on stack for result 
movea.] 8САб), Аб ; region handle into AQ move.w 


O The Definitive MacTutor, Vol. 4 


(Аб), AD 
07 


myBUF (A52, A1 


; dereference => pointer in Аб 
; Set area to zero 
; lowest address of x list 


; see whether it is а rect and if so 


- do the job here 


810 (Аб) 
morework 
4(А0),01 
8(A0),D2 
2CA0),D3 
6САд 2,04 
01,02 
03,04 
02,04 
04,07 
бопе 


10CA0), AQ 


#5 12,03 

of x values 
D3,A1 

А1,А2 

A1,A3 
8-1,(A1) 


; is this a single rectangle 
; if not do the big job 

; left 

; right 

; top 

; bottom 

; width 

; height 

; агеа іп 04 

; lower word into 07 


; get ready for some serious work 
beginning of region info 


size of buffer to hold ordered list 


; highest address in buffer 

; сору in A2 

; enother in АЗ 

; -1 in highest x address so that 1st 


x entry will be greater 


; read in y coordinate of next 


hor izontalboundary 

(Аб)+, 03 ; latest y value 

calc 

САЙ )+,01 ; new x value 

8$7fff,D1 ; flag indicates no more x values at 
this y 

storex ; if no flag, it is а new x 
(A0),D1 ; next word of region info 
8$7fff,D1 ; 811 done? 

done ; Ues go home 

getu ; no, get next у 


in ordered list 


АЗ,А1 
ordered list 
(А12,01 
елігу 

81 

116% 

82 АЗ 

getx 


-2(А3),АЗ 
new x 
insert 

on top 


(А1)+,-4(А1) 
(А12,01 
remove 
insert 

А1,А2 

mkroom 


in list 
01,-(А1) 


; place new x value in proper place 
; A8 points to highest x value іп 
; compare new x value to largest 

; if not equal, it must be added to 
; if match, remove from list 


; next x 


add а space at high end of list for 


`. 


if new x value is greatest, put it 


we 


; new x is not greatest so we must 
move list values up to make room 
move data up (1 word net distance) 
compare next list entry 

if it matches, remove it 

it is greater, so put it above 
are we at bottom? 

no, move another one up 


њо We We We We `. 


insert new x value in ordered place 


we 


; insert above present location 
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бга 


remove: 
subq 


ri: 
cmpa. | 
beq 
move .w 


bra 


shrink: 
addq 


bra 


calc: 
sub.w 
neg.w 


new: 
сіг.1 
clr.1 
movea. | 


dx: 


стра. 1 
bne 


nulu 
add. 1 
move .w 
rts 


morex: 


move .м 
sub.w 


пед.” 
add.w 
bra 


done: 
move. 1 


movem. 1 
unik 
move. | 
eddq. | 
jmp 


end 


ge tx 


82,A1 


А1, АЗ 
shr ink 


-(AD,4( D 


replace 
r1 


84 АЗ 
by 2 words 
getx 


that we erased 


03,04 
04 


02 

01 
A2,A1 
in list 


been used. 


А1,АЗ 
116% 
morex 
used 
D4,D2 
02,07 
D3,D4 


-СА12,01 
-(A1),D1 


we We 


we We 


`. 


`. 


we We We 


we 


J 


ereses ап entry from the list 
point to next higher 


is it the top? 
yes so exit 
move greater x values down to 


value removed 


if а match occurred, list shrinks 


one that we didn't insert end one 


determine new Height 
Y old - Y new 
Height of the rectangle(s) 


prepare for Width calculation 
Will receive width 

work reg 

reset A1 to point to least x value 


check to see if all x pairs have 


multiply H x W and add to area 
A3 points to greatest x value in 


if not equal, not all x’s have been 


HxVW 
edd to accumulating area 


; for next time 


; Subtracts x values in pairs adding 
differences to accumulating W 
; Xi (lower x value of а pair) 


д 


boundery segment) 
; Х1+1 - Xi (correct sign) 


D1 
D1,D2 
dx 


D7, 12CA6) 
parameter 


7 
; 


д 


(АТ2%,А0-АЗ/00-07 


Аб 
(АТ)+,Ай 
84 AT 
(A0) 


we o We We 


; Xi - Xi*1 Clength of a horizontal 


‚ W Сада to accumulating width) 


. store result “under” the last 


; restore registers 
restore original stack 
get return address 
remove parameters 
return this way 


The same algorithm can be used with the very convenient 
inline assembly facility of the Megamax and other C develop- 
ment systems. Because these compilers take care of “tending the 
stack” for you, the entry and exit procedures are significantly 
simplified. For the Megamax systems, they are as follows: 


acountpix( theregion) 


rgnhandle 


int 
esn( 


384 


theregion; 


buf (10001; 


поуе.1 (һегедіоп(Аб),Ай ; regionhandle note: local 
variables are referred off A6 

move.] (А0),А0 ; dereference once => region pointer 

с1г.1 07 ; Set erea to zero 

lea  buf(A62,A1 ; lowest address of x list 


rectcheck : 


/* Everything in between is the same аз in ACountPix.Asm 
ebove */ 


done: 
моуе.1 D7,numpixCA4)  ;report the answer note: global 
variables are referred of fA4 
) 
) 


This is the code for ош main calling program as ітріе- 
mented in Turbo Pascal: 


(PasArea.Pas ) 
Усору: л 1987 by Stephen Dubin, V.M.D.and Thomas И. Moore,Ph.D. 


(Prepared with Turbo Pascal V1.0 

( Users of other Pascal systems should particularly check the 
*preamble^) 

( portion of their program (Linking directives, “uses”, “in- 
cludes”, etc.) 

( бш check usage of {уре *point^ - TML doesn't like use of pt.h 
апа 

( pt.v аз control elements іп а for statement. ) 


progrem РазАгеа; 


($R-) ( Turn off range checking ) 
($1-) ( Turn off I/0 error checking ) 
($R PesArea.rsrc) ( Identify resource file ) 
($U-) ( Turn off auto link to runtime units  ) 
($L ACountPix.Rel ) ( Link in Assembly Language Segment) 

(0%) ( Embed Procedure Labels ) 


uses Memtypes,QuickDrew,OSIntf , ToolIntf ,PeckIntf; 


const 
FileMenuID s 1; ( the File menu) 
OptionMenuID = 2; ( the option menu) 


WindResID s 1; ( the resource id of my window) 
type 

BUF = erray[1..512) of Integer; ( Make it bigger if you ere 
really paranoid} 


var 
myMenus : Array(FileMenuId. .OptionMenuID] of MenuHandle; 
Done : Boolean; 
MyWindow : WindowPtr; 
TotalRegion RgnHandle; 
Numpix : . Longint; 
nyBUF : BUF; 


function ACountPixC theRegion:RgnHandle) : LongInt; external; 


function CountPixCtheRegion : RgnHandle): LongInt; 


ver 
pt : Point; 
rgn : Region; 
temp :  LongInt; 
X : Integer; 
U : Integer; 
begin 
temp := 0; 
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гоп := theRegion^^; 
for x := rgn.rgnBBox.left to rgn.rgnBBox.right do 


begin 
pt.h := x; 
for y := rgn.rgnBBox.top to rgn.rgnBBox.bottom do 
begin 
pt.v := y; 
if PtInRgnC pt, TheRegion) then temp := temp + 
1; 
end; 
end; 


CountPix := temp; 
end; 
( 2 seems to accept pt.h and pt.v as contro] elements but TML 
does 
( not. Some format checkers agree with TML) 


procedure Wipe; 

var 
г : Весі; 

begin 
SetRect(r,20,0,504,300); 
EraseRect(r); 

end; 


procedure Data; 


var 
rgn : Region; 
rgnpntr - i 
size Integer; 
thebuf : ВОР; 
bfpntr |: Ptr; 
myString :  Str255; 
1 : Integer; 
X : Integer; 
U : Integer; 
begin 
Wipe; 
TextSize(9); 
TextFont(Monaco); 
гоп := totalRegion^^; 


rgnpntr := ptr(totalRegion 2; 

size := rgn.rgnSize; 

if size > 800 then size:= 800; 

bfpntr := ptrCéthebuf 5; 

BlockMoveCrgnpntr,bfpntr,size); 

МоуеТо( 10, 10); 

DrawStringC'Here are the first 400 words of the region data. 
(FLAG = 327672”); 

:= 10; 


or i :=1 to (size div 2) do 
begin 
МоуеТо(х, y); 
NunToStr ingCtheBuf Г11,тубігіпа); 
if theBuf [i] < 32766 then 
begin 
if theBuf [1] <18 then DrawString(’ б); 
if theBuf [i] «1909 then DrawString(’ '2; 
if theBuf[il < 1000 then DrawString(' '2; 
if theBuf[il < 10000 then DrawString(’ б; 
DrawStr ing(MyStr ing); 
end; 
if theBuf [i] > 32766 then DrawString(’ FLAG’); 
x := x + 30; 
if Ci mod 16) = 0 then 


begin 
x := 10; 
y := у+10; 
end; 
end; 
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end; 


procedure OvalRegion; 
var 
RectA : Rect; 


begin 
Wipe; 
TotalRegion := NewRgn; 
SetRect(RectA, 170, 175, 195,200); 
OpenRgn; 
ShowPen; 
Ггате0уа1 (Кес{А); 
HidePen; 
CloseRgn(TotalRegion); 
end; 


procedure Contour; 


var 
pl : Point; 
p2 : Point; 
OldTick : Longint; 
begin 
Wipe; 


TotalRegion := NewRgn; 
OldTick := TickCount; 
Repeat 

Ge tMouse(p1); 

MoveToCp1.h,p1.v); 

p2 := pl; 
Until Button = True; 
OpenRgn; 
ShowPen; 
PenMode(patXor ); 
Repeat 

Ge tMouse(p2); 

Repeat Until COldTick € TickCount); 

LineToCp2.h,p2.v); 
Until Button € True; 
Repeat Until COldTick € TickCount); 
LineTo(p1.h,p1.v); 
PenNormal; 
HidePen; 
CloseRgn(TotalRegion); 
Inver tRgn(TotalRegion); 

end; 


procedure Example; 


begin 
Wipe; 
OpenRgn; 
TotalRegion := NewRgn; 
ShowPen; 
MoveToC 100, 100); 
LineTo(C200, 100); 
LineToC200,220); 
(ілеТ0( 180,229); 
LineTo( 180, 150); 
LineTo( 125, 150); 
LineTo( 125, 170); 
LineTo( 125, 170); 
LineToC 100, 170); 
LineToC 100, 100); 
HidePen; 
CloseRgn(TotalRegion); 

end; 


procedure FreeBox; 


var 
pl : Point; 
p2 : Point; 
p3 : Point; 


385 


OldTick : Longint; 
MyRect : Rect; 


begin 

Wipe; 

TotalRegion := NewRgn; 

OldTick := TickCount; 

PenPat(gray); 

PenMode(patXor 2; 

Repeat 

Ge tMouse(p 1); 

p2 := pl; 

Until Button = True; 

OpenRgn; 

ShowPen; 

PenMode(patXor 2; 

Керегі 

Pt2Rect(p1,p2,MyRect); 

Repeat Until COldTick € TickCount); 

FrameRect(MyRect); 

Repeat 

GetMouse(p3); 

Until EqualPt(p2,p3) © True; 
Repeat Until COldTick © TickCount); 
FrameRect(MyRect); 
p2 := рз; 

Until Button © True; 
Pennormal; 
HidePen; 
PenPatCblack2; 
FrameRect(MyRect); 
CloseRgn(TotalRegion); 
Inver tRgn(TotalRegion),; 
end; 


procedure Area; 


var 
NumTix :  LongInt; 
MoreTix :  LongInt; 
TicString :  Str255; 
PixString :  Str255; 
begin 
TextFont (Monaco); 
TextSize(9); 
Tex tMode(@); 


MoveTo( 10,20); DrawString(’ Using Pascal “); 
NumTix := TickCount; 
NumPix := CountPixC TotalRegion ); 
МогеТіх := TickCount - NumTix; 
NunToStr ingCMoreTix,TicString); 
NumToStr ingCNumP ix, PixStr ing); 
MoveToC 10,30); DrewStringC' Tickcount = '2; 
МоуеТо( 120,30); DrawString(TicString); 
МоуеТ0( 10,40); DrawString(’ Pixel Number = ‘); 
МоуеТо( 120,40); DrawStringCPixString); 
МоуеТ0( 10,50); DrawString(’ Using Tom Terrific “); 
NumTix := TickCount; 
NumPix := ACountPixC TotalRegion 2; 
MoreTix := TickCount - NumTix; 
NunToStr ingCMoreT ix, TicString); 
NunToStr ingCNumP ix, PixStr ing); 
МоуеТо( 10,60); DrawStringC' Tickcount = ”); 
MoveTo( 120,60); DrawString(TicString); 
МоуеТо( 10,70); DrawString(’ Pixel Number = ”); 
MoveTo( 120,70); DrawString(PixString); 

end; 


procedure ProcessMenu(codeWord : Longint); 
var 

menuNum : Integer; 

itemNum : Integer; 


begin 


386 


if codeWord o В then 
begin 
menuNum := HiWordCcodeWord); 
itemNum := LoWord(codeWord); 
case menuNum of 
FileMenuID :Done := true; 


OptionMenuID : 
begin 
case ItemNum of 
1:Contour; (Contour) 
2:FreeBox; (Freebox) 
3:0valRegion; (Oval) 
4:Exemple; (Exemple) 
5: Area; (Area 
6:Date; (Region Data) 


end; ( of ItemNum case) 
end; ( of MenuNum case) 
end; 
HiliteMenuC0); 
end; 
end; 


procedure DealWithMouseDownsCtheEvent: EventRecord); 
var 

location : Integer; 

windowPointedTo : WindowPtr; 

mouseloc : point; 

windowLoc : integer; 

VandH : Longint; 

Height : Integer; 

Width : Integer; 


begin 
mouseLoc := theEvent.where; 
windowLoc := FindWindow(mouseLoc, windowPointedTo); 
case windowLoc of 
inMenuBar : 
begin 
ProcessMenu(MenuSelect(mouseLoc22; 
end; 


end; 
end; 


procedure MainEventLoop; 
var 
Event : EventRecord; 
theItem : integer; 


begin 
repeat 
SystemTask; 
if GetNextEventCeveryEvent, Event) then 
begin 
cese Event.what of 
mouseDown : DealWithMouseDowns(Event), 
end; 
end; 
until Done; 
end; 


procedure MakeMenus; 


var 
index : Integer; 
begin 
for index :- FileMenuId to OptionMenuID do 
begin 
туМепиѕ (іпдех ) := GetMenuCindex); 
Inser tMenuCmyMenus index 1,02; 
end; 
DrawMenuBar ; 
end; 
( Main Program ) 
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begin 
Done := false; FlushEventsCeveryEvent, 0); 
InitGraf CéthePort); InitFonts; 
InitMenus; InitDialogs(ni1); 
InitCursor; 
MoreMasters; 
MoreMasters; 
MakeMenus; 
MyWindow := GetNewWindow(WindResID,ni,Pointer(C- 122; 
SetPortCMyWindow); 
TotalRegion := NewRgn; 
"Area" first) 
MainEventLoop; 
end. 


InitWindows; 


(Lazy way to avoid bomb if your select 


Here is the resource file for use with the above program 
(Turbo Pascal): 


x 
х Resource listing from file: "PasArea.R". 
x 


PasArea.rsrc 


Type AREA = STR 
0 
РазАгеа, by Stephen Dubin and Thomas W. Moore Copyright € 1987 


Type WIND 
1 


Fun with Regions II 
40 5 330 505 
Visible NoGoAway 

Ü 

0 


Туре MENU 
21 

File 
Quit 


72 

Option 
Contour 
Freebox 

Oval 

Example 
Compute Area 
Region Data 


In order to compile the same program with TML Pascal 
V2.0, a few minor adjustments were needed. The preamble was 
changed to: 


program TMPasArea; 
($T APPL AREA) { set the 5a and creator) 


(8%) — (set the bundle bit 
($L TMPasAreaRes) ( link the resource file too...) 


( Constant, Type and Variable declarations as above are the same 
as in PasArea.Pas above) 


( Declare the Assembly Language routine as external ) 
function ACountPixC theRegion:RgnHandle) : LongInt; external; 
($U ACountP ix 

( This directive will not appear in the . link file unless it follows 
the declaration of the ) 

( relocatable object file as external) 


The only change needed in the body of the program was in 
the high level CountPix function. A form that compiled with 
TML is: 


function CountPixCtheRegion : RgnHandle): LongInt; 


var 
pt : Point; 
rgn : Region; 
temp LongInt; 
x : Integer; 
y : Integer; 
begin 
temp := 0; 
гоп := theRegion^^; 
for x := rgn.rgnBBox.left to rgn.rgnBBox.right do 
begin 
pt.h := x; 
for y := rgn.rgnBBox.top to rgn.rgnBBox.bottom do 
begin 
pt.v := y; 
if PtInRgn€ pt, TheRegion) then temp := temp 
+ 1; 
end; 
end; 
CountPix := temp; 
end; 


TML does not seem to like having pt.h and pt.v as control 
elements. PasMat, a Pascal formatting and syntax checking 
program, agrees with TML on this point. In keeping with our 
local traditions, the first non-comment line of our TML resource 
Ше was “TMPasAreaRes”. Although it probably is of little 
interest in these days of monstrous memories, the TML version 
of the program requires 3,305 bytes of memory; whereas the 
Turbo program weighs in at a hefty 10,855 bytes. 

Some final zingers for the reader - Although it was certainly 
necessary for usto use assembler to plumb the depths of the ROM 
and to work out the algorithm for making our area measurement 
lightning fast; one might consider whether the same algorithm 
might now be implemented entirely from C, Pascal or possibly 
Basic. Would the speed be degraded to any appreciable extent? 
Willanew call AreaRgn be found inthe 512K Roms on the Mack 
III's? 


ом! 
uses MacIntf ; SASER 
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Programmer s Workshop 


Menus In Windows 


[Jim Matthews is а software developer at Dartmouth, work- 
ing on network applications. He has done maintenance work on 
DarTerminal, an AppleTalk terminal emulator, and has worked 
on developing a Macintosh mail system. He started program- 
ming in high school on an IBM 360 with core memory but slowly 
moved to smaller, newer machines. Incollege, he helped develop 
MacFunction, a three-dimensional graphing program that is 
currently marketed by True Basic, Inc.] 

Menus in Windows 
by Jim Matthews, Dartmouth College 

One of the critical elements of the Macintosh user interface 
is the menu bar. It relieves the user of the need for memorizing 
command names and gives easy access to a large number of 
operations in a small amount of space. Nonetheless, the limita- 
tions of the standard Macintosh menu bar have become increas- 
ingly evident. Large screens make the fixed position of the menu 
bar less convenient, and large programs present users with an 
overwhelming number of available commands. Desk accesso- 
ries have never been able to use the menu bar fully, limiting their 
potential. Both Apple and third parties have developed worka- 
rounds to the limitations of the menu bar. Hierarchical and pop- 
up menus, implemented in System 4.1, provide alternate ways of 
structuring menu commands. Тһе tear-off palettes used in 
HyperCard and MacPaint 2.0 add a new dimension to menus, as 
do the tear-off menus provided with Radius displays. 

Still, I recently felt the need to extend the menu bar concept 
by another step. While developing a program with a large 
number of commands, I decided that what I wanted was a 
different menu bar for each window. It would have been possible 
tochange the menu bar depending on which window was in front, 
but the commands needed by each window were so different that 
the user would never know what to expect when he pulled down 
a menu. Furthermore, I wanted to leave open the possibility of 
turning the program into a desk accessory, and I could not fit all 
my commands into one menu. So I re-implemented part of the 
Menu Manager to provide for window-specific menu bars. The 
code itself is not very complicated — I was fortunate to be 
preceded by Mike Schuster, whose December, 1985 article on 
pop-up menus provided a wealth of useful information. The 
routines I produced met my needs admirably, but like any 
extension to the standard interface they also raised some tricky 
issues. 


The wMenu Manager Routines 
Because wanted to produce menu bars that function exactly 
like the one at the top of the screen, I implemented the window 
menus by imitating eight standard Menu Manager routines. They 
all operate on a wMenuBar data structure which is roughly 
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comparable to a MenuList. 


type 

wMenuRec = record 
mh : MenuHandle; 
titleRect : Rect; 


end; 
wMenuBar = record 
numMenus : integer; 
hilited : integer; 
gp : GrafPtr; 
wMenus : array [9..0] of wMenuRec; 
end; 


The wMenuBar stores the number of menus in a menu bar, 
which one is hilited (if any), and the GrafPort in which the menu 
bar is drawn. In addition, it stores a menu handle and a rectangle 
for each menu that has been inserted. The rectangle specifies the 
coordinates of the menu title; i.e. the area that is inverted when 
a menu is selected. This is a bit wasteful, since two of the 
rectangle's coordinates are always the same, but it makes the 
code simpler. The wMenuBar record is created by a call to 
wlInitMenus, which allocates the storage and returns a 
wMenuBarHandle. The rest of the routines accept the same 
arguments as their Menu Manager equivalents, with the addition 
of a wMenuBarHandle to specify the menu bar being altered. 
The routines are wInsertMenu and wDeleteMenu, to add and 
remove menus from the menu bar; wClearMenuBar to delete all 
the menus; wDrawMenuBar to redraw the menu bar; wMenuSe- 
lectand wMenuKey to respond to mouse and key events, respec- 
tively; and finally, wHiliteMenu to highlight a menu's title. 


Implementation Issues 
There are a few subtle points in the implementation of the 


= ш$атр!е = = 
é File ЕЖП! 
Undo #2 
Cut 9H 
Copy ^ ÆC 
Paste %U 


Clear 


Menus Оо go in windows. 


Figure 1. Edit Menu 
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wMenu Manager. The System 4.2 menu definition procedure 
has a bug that is fixed by initializing the low memory global 
TopMenultem in wInitMenus. Calls to the menu definition 
procedure are implemented using inline machine code, since 
Pascal doesn't provide a standard way to call a routine based on 
its address. WMenuKey walks down a menu's data looking for 
acertain command key equivalent, and the dynamic nature of the 
data structure requires some ugly code. GetNextEvent and 
SystemTask are called in the inner loop of the menu selection 
code: this means that keyDown events are swallowed while the 
user is holding down a menu, but it provides the ability to produce 
screen dumps and keeps desk accessories updated. With the 
standard menu bar it is impossible for the user to drag the mouse 
above the top of the menus, but with window menus it was 
necessary to deal with this case. I decided to have the displayed 
menu disappear when the user moved the mouse above a 
window 's content region, but that could easily be changed. 

The wMenu routines can be substituted for Menu Manager 
ones with a few exceptions. Unlike InitMenus, wInitMenus must 
not be called until there is a window to put the menu bar in. 
wDrawMenuBar should be called in response to update events, 
since the Window Manager considers the menu bar part of a 
window's content region. This also means that wMenuSelect 
should be called in response to mouseDown events in a window's 
content region. А program should continue call MenuSelect and 
MenuKey at appropriate times to give the user access to desk 
accessory menus. 

The wMenu routines make it fairly easy to implement a 
number of different menu bars in one program, but that can lead 
to an explosion of possible commands. The nested case state- 
ments that typically handle menu commands can become un- 
wieldy when the number of menu bars exceeds two or three. 


Interface Issues 
Menus in windows have the significant disadvantage of 
being a departure from the standard way of doing things. Users 
do not expect to find a menu bar inside a window, and can be 
confused by one. If there is more than one menu bar visible the 
user may wonder which to use, and if the user types a command 


Rccess Privileges 
Alarm Clock 
Calculator 
Chooser 


Control Panel 
DeskZap 
Find File 


HeapShowSs 
JumpStart Log 
Key Caps 

M| New Scrapbook 

И! TimeOut 


Figure 2. Scrolling Menu 
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Figure 3. Project Window 


key equivalent it may not be clear which menu bar is handling it. 
This problem becomes especially difficult when some com- 
mands are available from the regular menu bar and others only 
from window menus. I have tried to use window menus for 
commands that only affect that particular window, and the 
regular menu bar for program-wide operations. This introduces 
a degree of modality into a program, but not much more than is 
present in any multiple-window application. 


Compatibility Issues 

The wMenu routines were written to be compatible with all 
post Mac 512 models. The 128k ROM calls HSetState and 
HGetState are used іп a few places; but if they were changed, I 
imagine the code would work on older Macs also. Given Apple's 
emphasis on the sanctity of the Window Manager's GrafPort, 
care was taken to make sure that menus are only drawn inside an 
application window's content region if they overlap they either 
scroll or are cropped. There are a couple of things that could 
cause future compatibility problems, though. First, the program 
modifies TopMenultem, and although the fix was made on the 
advice of Mac DTS, it could break on future systems. Secondly, 
Apple is now asking programmers not to rely on the internal 
Structure of menu records. The wMenuKey routine could not be 
written without doing this, so it is vulnerable to future changes. 
The code emulates the pre-Mac SE Menu Manager in that color 
and hierarchical menus are not supported. The code has been 
tested on machines from the 512KE to the Mac II without mishap. 


wSample 

I have included a wMenu version of the sample program 
found in Inside Macintosh Vol. I. This example illustrates how 
the wMenu routines are called and demonstrates how the menus 
appear to the user. Itis not, however, acase where window menus 
add much to the program. Window menus are much more 
appropriate when there are multiple windows, each with signifi- 
cantly different functionality. I originally implemented them as 
part a mail program that had separate windows for composing 
letters, reading mail, and organizing a mailbox. In that case, 
window menus let me compartmentalize the program's interface 
and use a large number of commands without overwhelming the 
standard menu bar. 


( «Menu Manager ) 
( by Jim Matthews ) 
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UNIT wMenu; 
INTERFACE 


USES 
ROM85; ( uses HGetStete and HSetState ) 


CONST 

mBarHeight = 20; 
betweenTitles = 15; 

( * of pixels between edjacent menu titles ) 
invertOverlep - 10; 

( * of pixels to invert on each side of а menu title ) 
noneHilited = -1; 

( value to store in wMenuBar.hilited if nothing hilited ) 
nmenuTitleBit = 31; 

( mac-style bit offset for menu title bit in enableFlags ) 


TYPE 
wMenuRec = RECORD 
mh : MenuHandle; 
titleRect : Кесі; 


END; 
wMenuBar - RECORD 
numMenus : integer; 


hilited : integer; 
gp : GrafPtr; 
wMenus : АКВАҮ(0..01 OF wMenuRec; 
END; 
wMenuBarPtr = ^wMenuBar; 
wMenuBarHandle - ^wMenuBerPtr; 


FUNCTION wInitMenus Сор : GrafPtr>) : wMenuBarHandle; 
PROCEDURE wInsertMenu CtheMenuBar : wMenuBerHendle; 
theMenu : MenuHandle; 
beforeID : integer); 
PROCEDURE wOrawMenuBar CtheMenuBar : wMenuBarHandle); 
PROCEDURE wDeleteMenu (theMenuBar : wMenuBarHandle; 
menuID : integer); 
PROCEDURE wClearMenuBar (theMenuBar : wMenuBarHandle); 
FUNCTION wMenuSelect CtheMenuBer : wMenuBarHandle; 
stertPt : Point) : longint; 
FUNCTION wMenuKey CtheMenuBar : wMenuBarHandle; 
ch : char) : longint; 
PROCEDURE wHiliteMenu (theMenuBar : wMenuBarHaendle; 
menuID : integer); 


IMPLEMENTATION 
(wInitMenus — create а wMenuBar and associate it with a 
gref port) 
FUNCTION wInitMenus; ( (ор: GrafPtr) : wMenuBarHandle; } 
| TYPE 
| іпіріг = ^Integer; 
VAR 
mbar : wMenuBarHendle; 
| TopMenuItemP : intptr; 
| BEGIN 


( Set low-mem global to fix menu display bug ) 
| TopMenuItemP := intptrC$A0A); 
TopMenuItemP^ := mBarHeight; 


mbar := wMenuBarHandle(NewHandle(sizeof CwMenuBar 222; 
mbar^^.numMenus := 0; 
mbar^^.hilited := noneHilited; 
mbar^^.gp := ор; 
wInitMenus :- mbar; 
END; ( wInitMenus ) 


(wInsertMenu - insert а menu into a def ined wMenuBar, } 
( analogous to InsertMenu ) 
PROCEDURE wInsertMenu; ( (theMenuBar : wMenuBarHandle; ) 
( theMenu : MenuHandle; ) 


390 


( beforeID : integer); ) 


VAR 
newSize : Size; 
r : Rect; 


i, 1: integer; 
titleWidth, oldSize, oldFont : integer; 
BEGIN 
newSize := sizeof (wMenuBar) + theMenuBar**.numMenus * 


sizeof CwMenuRec); 


IF newSize > GetHandleSizeChandle( theMenuBar )) THEN 
Se tHandleSizeChandle( theMenuBar), newSize); 
IF MemError = noErr THEN 
BEGIN 
oldSize := thePort^.txSize; 
oldFont := thePort*.txFont; 
TextSizeC 12); 
TextFont(systemFont); 
titleWidth := StringWidth( theMenu**.menuData); 
TextSizeColdSize); 
TextFontColdFont); 
і := 0; 
IF beforeID › В THEN 
( Insert the menu before а particular one? ) 
BEGIN 


1 := 0; 
WHILE CtheMenuBar^*^.wMenus[il.mh^^.menuID €? 
beforeID) AND Ci < theMenuBar^^.numMenus) 00 
1 := 1+1; 
IF i € theMenuBar^^.numMenus THEN 
BEGIN 
FOR j := theMenuBar^^.numMenus DOWNTO i + 1 
DO 
BEGIN 
theMenuBar^^.wMenus(jl.mh := 
theMenuBar^^.wMenus[j - 11.тһ; 
theMenuBar ^^ .wMenus[jJ.titleRect := 
theMenuBar^^.wMenus[j - 1).titleRect; 


OffsetRectCtheMenuBar^^ .wMenus[j].titleRect, titleWidth + 
betweenTitles, 0); 
END; ( for loop - copying menus back ) 
END; ( if there's a menu id = beforeID ) 
END ( if beforeID € 0) 
ELSE ( if beforeID «s 0, put it efter the rest ) 
i := theMenuBer^^ .numMenus; 
WITH theMenuBar^^ .wMenus[ il DO 
BEGIN 
titleRect.top := 1; 
titleRect.bottom := mBarHeight - 1; 


IF i = 90 THEN 
titleRect.left := betweenTItles - invertOver lap 
ELSE 


titleRect.left := theMenuBar^^ .wMenus(i - 

1).titleRect.right + betweenTitles - 2 * invertOverlap; 

titleRect.right := titleRect.left + titleWidth + 
2 * invertOverlap; 

mh := theMenu; 

END; ( with theMenuBar^^.wMenus[il ) 
theMenuBar^^.numMenus := theMenuBar**.numMenus + 1; 
END; ( no MemError ) 
END; ( wInsertMenu ) 


( wDrawMenuBar - draw the wMenuBar, with appropriate) 
( highlighting ) 
PROCEDURE wDrawMenuBar; ( CtheMenuBar : wMenuBarHendle); ) 


VAR 
i : integer; 
r : Rect; 


oldPort : GrefPtr; 
oldSize, oldFont, oldMode : 
oldStyle : Style; 
bmap, oldMap : BitMap, 
BEGIN 
GetPortColdPort); 


integer; 
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Se tPor t( theMenuBar**.gp); 
oldSize := thePort*.txSize; 
oldFont := thePort*.txFont; 
oldMode := thePort^.txMode; 
oldStyle := thePort^.txFace; 
TextSize( 12); 
TextFontCsystemFont); 
TextModeCsrcOr?; 
TextFaceC[ 12; 


SetRect(r, 0, 0, 10000, mBarHeight); 
EraseRect(r); 

МоуеТо(@, mBarHeight - 1); 

ілес 18008, 0); 


FOR i := 0 TO theMenuBar^^.numMenus - 1 DO 
BEGIN 
MoveToCtheMenuBar^^ .«Menus( il.titleRect.left + 
invertOverlap, mBarHeight - 5); 
DrawStr ing( theMenuBar ^" .wMenus[i].mh**.menuData); 


( gray-out disabled menu titles ) 

IF NOT 
BitTstCétheMenuBar^^.wMenus[il.mh^^.enableFlags, menuTitleBit) 
THEN 

BEGIN 
г := theMenuBar**.wMenusl[i].titleRect; 
r.left :=r.left + invertOverlap; 
r.right := r.right - invertOver lap; 
bmap.bounds := г; 
Of fsetRect(bmap.bounds, -r.left, -r.top); 
IF Cbmap.bounds.right MOD 16) © Ø THEN 
bmap.rowBytes := 2 * ((bmap.bounds.right DIV 


16) + 1) 
ELSE 
| bmap.rowBytes :- 2 * (bmap.bounds.right DIV 
16); 
bmap.baseAddr :- NewPtr(bmap.rowBytes * mBar- 
Height); 
oldMap := thePort^.portBits; 
SetPortBits(bmap); 
FillRect(bmap.bounds, grau); 
SetPortBits(oldMap); 


HLockChandleCtheMenuBar 2); 
CopyBitsCbmap, thePort^.portBits, bmap.bounds, г, 
notSrcBic, NIL); 
HUnlockChandleCtheMenuBar 22; 
DisposPtr(bmap.baseAddr); 
END; ( if title disabled ) 
END; ( for each menu ) 
IF theMenuBar^^.hilited © noneHilited THEN 


Inver tRect( theMenuBar** .wMenus[ theMenuBar** .hilited].titleRect); 
TextSizeColdSize); 
TextFontColdFont); 
Tex tMode(oldMode ); 
TextFaceColdStyle); 
SetPortColdPort); 
END; ( wDrawMenuBar ) 


(wDeleteMenu - delete a menu from а wMenuBar} 
PROCEDURE wDeleteMenu;  ( CtheMenuBar : wMenuBarHandle; } 
( menuID : integer); ) 
VAR 
i, j, oldSize, oldFont : integer; 
oldStyle : Style; 
titleWidth : integer; 
BEGIN 
oldSize := thePort*.txSize; 
{ reset the font/size/style to compute menu title widths } 
oldFont := thePort^.txFont; 
oldStyle := thePort^.txFace; 
TextSize( 12); 
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TextFontCsystemFont); 
TextFaceC[ 1); 


і := 0; 
WHILE CtheMenuBar^^ .wMenus[i].mh^^.menuID € menuID) 
AND (i < theMenuBar^^.numMenus) DO 
i := i+ b 
IF i € theMenuBar^^.numMenus THEN 
BEGIN 
titleWidth := 
StringWidth( theMenuBar**.wMenus[i].mh**.menuData); 
FOR j := i TO theMenuBar^^.numMenus - 1 DO 
BEGIN 
theMenuBar**.wMenus[j].mh := 
theMenuBar^^.wMenus[j + 1J.mh; 
theMenuBar* ^ .«Menus[jl.titleRect := 
theMenuBar^^.wMenus(j + 1lJ.titleRect; 
Of fsetRect( theMenuBar** .wMenus[ jl. titleRect, - 
CtitleWidth + betweenTitles), 0); 
END; ( for loop - copying menus back } 
theMenuBar**.numMenus := theMenuBar^^.numMenus - 1; 
END; ( if there's а menu id = menuID } 


TextSizeColdSize); 

TextFontColdFont); 

TextFaceColdStyle); 
END; ( wDeleteMenu ) 


(wClearMenuBar - delete all the menus in a menu bar) 
PROCEDURE wClearMenuBar; ( CtheMenuBar : wMenuBarHandle); ) 
BEGIN 

theMenuBar^^.numMenus := 0; ( take the easy way out.... ) 
END; ( wClearMenuBar ) 


(MenuDefProc - inline call to the menu definition procedure) 
Pop the address of the proc off the stack and jsr to it) 
PROCEDURE MenuDefProc (message : integer; 
theMenu : MenuHandle; 
VAR menuRect : Rect; 
hitPt : Point; 
VAR whichItem : integer; 
theProc : ProcPtr); 
INLINE 
$205F, $4Е90; ( pop.1 Ай, jsr (Ай) ) 


(MenuDefGlue - dereference menu handle to find the add. of) 
( the definition proc and call it using MenuDefProc, above) 
PROCEDURE MenuDefGlue (message : integer; 
theMenu : MenuHandle; 
VAR menuRect : Rect; 
hitPt : Point; 
VAR whichItem : integer); 
BEGIN 
MenuDefProc(message, theMenu, menuRect, hitPt, whichI tem 
theMenu*^ ^ .menuProc* 2; 
END; 
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Тт - pull down the menus and let the user select an 
item 
FUNCTION wMenuSelect; ( (theMenuBar : wMenuBarHandle; ) 
( startPt : Point) : longint; ) 


CONST 
f lashDelay - 3; ( * of ticks between calls to 
invert selected item ) 
menuFrame = 2; { width of menu frame } 


MenuF lashAddr = $424; 
( address of lo-mem global: 8 of times to flash menu } 
TYPE 
intPtr = “integer; 
VAR 
bmap : BitMap; 
menuRect : Rect; 
oldClip : RgnHandle; 
nilPt : Point; 


391 


blink, whichItem : integer; 
oldPort, wMgrPort : GrafPtr; 
і : integer; 
hstate, mprocState : SignedByte; 
ticks : longint; 
menuFleshP : intPtr; 
oldSize, oldFont, oldMode : 
pnState : PenState; 
strayed : boolean; 
dummyEvt : EventRecord; 
BEGIN 
hState := HGetStateChandleCtheMenuBar 2); 
HLockChand1e¢ theMenuBar 22; 
GetPortColdPort); 
SetPortCtheMenuBar^* ^ ар); 
oldSize := thePort*.txSize; 
oldFont := thePort*.txFont; 
oldMode := thePort^.txMode; 
TextSizeC 12); 
TextFontCsystemFont); 
TextModeCsrcOr?; 
menuFlashP := intPtr(MenuF lashAddr 2; 
whichItem := 0; 
WHILE WeitMouseUp DO ( loop while the mouse is down ) 
BEGIN 
( find menu title that user is clicking on ) 
1 := theMenuBar^^.numMenus - 1; 
WHILE Ci >= Ø) AND NOT PtInRectCstertPt, 
theMenuBar**^ .wMenusli].titleRect) DO 
i := i - 1; 


integer; 


(АҒ user is clicking menu title, have the menu “drop down” ) 
IF i >= 0 THEN 
WITH theMenuBar^^ .wMenus( i] 00 
( note: theMenuBar is locked ) 


wHiliteMenuCtheMenuBar, mh^*.menuID); 
( hilite title ) 
CalcMenuSizeCmh); 
( calculate menu size, it may have changed ) 
SetRect(menuRect, titleRect.left + 1, mBar- 
Height, titleRect. left + mh^^.menuWidth + 1, mBarHeight + 
mh** .menuHe ight); 
InsetRect(menuRect, -menuFrame, -menuFrame); 


{ if the menu overlaps the edges of the window, trim it } 
IF menuRect.bottom > thePort^.portRect.bottom THEN 
menuRect.bottom := thePort^ .portRect .bottom; 
IF menuRect.right > thePort^.portRect.right THEN 
OffsetRectCmenuRect, thePort^.portRect.right 
- menuRect.right - 2, 0); 
IF menuRect. left < 0 THEN 
OffsetRect(menuRect, -menuRect. left, 0); 
bmap.rowBytes := CCmenuRect.right - 
menuRect.left + 15) DIV 16) * 2; 
bmap.bounds := menuRect; 
bmap.beseAddr := NewPtr(bmap.rowBytes * 
(nenuRect.bottom - menuRect.top)); 
IF bmap.baseAddr © NIL THEN 
( proceed if there is memory ) 
BEGIN 
CopyBitsCthePort^.portBits, bmep, 
bmap.bounds, bmap.bounds, srcCopy, NIL); 
OldClip := NewRgn; 
GetClipColdClip); 
ClipRect(menuRect); 


{ draw the menu - thanks to Mike Schuster, MacTutor 12/85 } 
IF mh^^.menuHeight › 0 THEN 
BEGIN 
InsetRect(menuRect, menuFrame, 
menuFrame ); 
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EraseRect(menuRect ); 
InsetRect(menuRect, -1, -1); 
FrameRect(menuRect ); 
InsetRect(menuRect, 1, 1); 


GetPenStateCpnState); 

PenNormal; 

MoveToCmenuRect.left + 1, 
menuRect.bottom * 1); 

LineCCmenuRect .right - 
menuRect. left), 0); 

ііле(0, -CnenuRect.bottom - 
menuRect. top)); 

SetPenStateCpnState); 

END; ( if there’re any menu items ) 


LoadResource(mh**.menuProc); 

mprocState := 
HGetStateChandle(mh** .menuProc)); 

HLock(mh** . menuProc?; 

whichItem := 0; 

MenuDefGlue(mDrewMsg, mh, menuRect, 
stertPt, whichItem); 


( send the mChooseMsg while the user is still in this menu ) 
strayed := false; 
WHILE WaitMouseUp AND NOT strayed DO 
BEGIN 
MenuDefGlueC(mChooseMsg, mh, 
menuRect, startPt, whichI tem); 
GetMouse(startPt); 
strayed := (stertPt.v « mBarHeight 
- 1) AND CstartPt.v > Ø) AND (NOT PtInRect(startPt, ti- 
tleRect)); 
IF i < theMenuBar^^.numMenus - 1 THEN 
strayed := strayed OR ((startPt.v < 
mBarHeight - 1) AND CstertPt.v > Ø) AND PtInRect(startPt, 
theMenuBar^^.wMenus[i + 11.titleRect?); 


( Enable FKeys (i.e. screen dump) and DA updating } 
IF EventAvailCeveryEvent, dummyEvt) 
THEN 


SystemTask:; 
END; ( while WaitMouseUp &not strayed ) 


( flash the menu if an item was selected ) 
IF CwhichI tem © 0) AND NOT strayed THEN 
FOR blink := 1 ТО menuFlashP^ 00 
BEGIN 
SetPt(nilPt, 0, 0); 
MenuDefGlueCmChooseMsg, mh, 
menuRect, nilPt, whichI tem); 
Delay(flashDelay, ticks); 
MenuDefGlue(mChooseMsg, mh, 
menuRect, startPt, whichItem); 
Delay(flashDelay, ticks); 
END; ( whichItem © 0) 
HSetStateCmh^^.menuProc, mprocState); 
SetClipColdClip); 
DisposeRgn(oldClip); 
CopyBitsCbmap, thePort^.portBits, 
bmap.bounds, bmap.bounds, srcCopy, NIL); 
DisposP tr Cbmap.baseAddr ); 
END; { memory for bitmap } 
END ( i >= Ø: found the hit menu title ) 
ELSE 
BEGIN 
( user isn’t over а menu, so unhilite the last one hilited ) 
IF theMenuBer^^.hilited O noneHilited THEN 
wHiliteMenuCtheMenuBar, 9); 
GetMouse(stertPt); 
( need а new startPt — mouse may have moved ) 
END; ( no menu currently selected ) 
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END; ( while WaitMouseUp - looking for a hit menu title) 


( user let up on the mouse - return the appropriate value ) 
IF whichItem = 0 THEN 
wMenuSelect := 0 
ELSE 
wMenuSelect := 
BitShiftCtheMenuBar^^.wMenuslil.mh^^.menuID, 16) + whichItem; 
TextSizeColdSize); 
TextFontColdFont); 
Тех{Моде(о1 Моде); 
SetPortColdPort); 
HSetStateChandleCtheMenuBar2, hState); 
END; ( wMenuSelect ) 


(wMenuKey - return the menu id and item no. with ch as it’s) 
( cmd-key equivalent ) 
( Caution: this assumes knowledge of the internal structure) 
( of MenuInfo.menuData ) 
FUNCTION wMenuKey; ( CtheMenuBar : wMenuBarHandle; ) 
( ch : char) : longint; ) 
CONST 
f leshDelay = 3; 
TYPE 


SignedBytePtr = “SignedByte; 
CharPtr = “char; 
VAR 
hState : SignedByte; 
bp, keyEquivP : SignedBytePtr; 
i, j, whichMenu, whichItem : integer; 
done, enabled : boolean; 
ticks : longint; 


( compare alphabetic characters w/o case sensitivity ) 
FUNCTION equalChars (cl, c2 : char) : boolean; 
BEGIN 

IF c1 IN ['a^..'z^] THEN 
СІ := сһаг(ога(с12 + ordC'A^) - ord(‘’a’)); 
IF c2 IN (7а”..7271 THEN 
c2 := charCord(c2) + ordC'A^) - ord(’a’)); 
equalChars := с! = c2; 


0; 


BEGIN 

i := 0; 

done := false; 

WHILE (МОТ done) AND Ci < theMenuBar^^ .numMenus) DO 

BEGIN 
hState := 
HGetStateChandleCtheMenuBar^^ .wMenus( i ] .mh22; 

HLockChandleCtheMenuBar^* .wMenus [i ] .mh22; 


( run down а menu, looking for ап item w/ ch as its key) 
( equivalent ) 
‘= 1; 
bp := 
SignedBytePtr(C8theMenuBar^*^ .wMenus[ i ] .mh^ ^ .menuData); 
bp := SignedBytePtrCord4(bp) + бр“ + 1); 
WHILE (NOT done) AND Cbp* © 0) DO 
BEGIN 
keyEquivP := SignedBytePtrCord4Cbp) + бр“ + 2); 
IF equalChars(ch, charCkeyEquivP*)) THEN 
BEGIN 
whichMenu := 
theMenuBar ** .wMenus[ i] .mh^^ . menuID; 
whichItem := j; 


done := true; 
END 
ELSE 
BEGIN 
j := j +1, 


bp := SignedButePtr(ord4(keuEquivP) + 3); 
D: 
END; ( looking through this menu ) 
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HSetState(handle(theMenuBar “.wMenus[il.mh), hState); 
1 := i+ l; 
END; ( while loop - looking for Кеу equiv ) 
(the item is enabled if both it and its menu title are) 
enabled := BitTst(@theMenuBar “.wMenus[i - 
1].mh°*.enableFlags, menuTitleBit); 
enabled := enabled AND (j < 32) AND 
(BitTstCétheMenuBar^^.wMenus[i - 1].mh**.enableFlags, menuTi- 
tleBit - j)); 
IF done AND enabled THEN 
BEGIN 
wHiliteMenuCtheMenuBar, whichMenu); 
wMenuKey := BitShiftCwhichMenu, 16) + whichI tem; 
END ( done ) 
ELSE 
wMenuKey := 0; 
END; ( wMenuKey ) 


(wHiliteMenu - unhilite the currently hilited menu title, and) 
( hilite a new one ) 
( if menuID o Ø ) 
PROCEDURE wHiliteMenu;  ( CtheMenuBar : wMenuBarHandle; ) 
( nenuID : integer); ) 
VAR 
i : integer; 
oldPort : GrafPtr; 
BEGIN 
GetPortColdPort); 
SetPortCtheMenuBar* ^ .gp); 
IF CtheMenuBar^^.hilited © noneHilited) THEN 


Inver tRect( theMenuBar**.wMenus[ theMenuBar^^ .hilited]. titleRect); 
theMenuBar^^.hilited := noneHilited; 
IF nenuID € 0 THEN 
BEGIN 


i := 0; 
WHILE CtheMenuBar^^.wMenus[i]l.mh^^.menuID © menuID) 
AND Ci < theMenuBar^^ .numMenus) 00 
1 := i+ l; 
IF i € theMenuBar^^.numMenus THEN 
BEGIN 
InvertRectCtheMenuBar*^*^ .wMenus[ i ]. ti tleRect); 
theMenuBar** .hilited := i; 
END; ( found menuID ) 
END; { menuID 90) 
SetPortColdPort); 
END; ( wHiliteMenu ) 


END. 

(wSample - the Mac User Education prog, adapted to use wMenus) 
( by Jim Matthews ) 

PROGRAM wSample; 


eppleID - 128; 
fileID = 129; 
- 1 


editID 30; 
eppleM - 1; 
fileM = 2; 
editM = 3; 


menuCount = 3; 
windowID = 128; 


undoCommand = 1; 
cutCommand = 3; 

copyCommand - 4; 
pesteCommand = 5; 
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clearCommand = 6; 


VAR 
myMenus : ARRAY[1..menuCount] OF MenuHandle; 
dragRect, txRect : Rect; 
textH : TEHandle; 
theChar : char; 
extended, doneFlag : boolean; 
myEvent : EventRecord; 
wRecord : WindowRecord; 
myWindow : WindowPtr; 
whichWindow : WindowPtr; 
myMenuBer : wMenuBerHendle; 


(SetUpWMenus - read in menu templates and set up wMenuBar) 
PROCEDURE SetUpWMenus; 
VAR 
i : integer; 
BEGIN 
myMenuBar := wInitMenus(myWindow); 
muMenus[appleM] := GetMenu(appleID); 
AddResMenu(muMenus[appleM], ‘DRVR’); 
myMenus[f ileM] := GetMenu(fileID); 
muMenus[editM] := GetMenu(editID); 


FOR 1 := 1 TO menuCount 00 
wlInsertMenu(muMenuBar, muMenus[i], 0); 
END; (SetUpWMenus) 


(DoCommand - handle menu commands) 
PROCEDURE DoCommand (mResult : longint); 
VAR : 
theItem, theMenu : integer; 
name : Str255; 
temp : integer; 
BEGIN 
theItem := LoWord(mResult); 
theMenu := HiWord(mResult); 


CASE theMenu OF 
appleID : 
BEGIN 
GetItem(nyMenus[appleM], theItem, name); 
temp := OpenDeskAcc(name); 


SetPor tCmyWindow); 
END; ( eppleID } 
fileID : 
doneflag := true; 
editID : 
BEGIN 


IF NOT SystemEdit(theItem - 1) THEN 
CASE theItem OF 
cutCommand : 
TECutCtextH2; 
copyCommand : 
TECopy( textH); 
pasteCommand : 
TEPesteCtextH); 
clearCommand : 
TEDeleteCtextH); 
END; ( cese theItem of ) 
END; ( editID) 
OTHERWISE 


END; ( case theMenu of ) 
wHiliteMenuCmyMenuBer, 0); 
END; ( DoCommand ) 


(main program) 
InitGraf CéthePort); 
InitFonts; 


FlushEventsCeveryEvent, 0); 
InitWindows; 
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InitMenus; 
TEInit; 
InitDialogs(NIL); 
InitCursor ; 


WITH screenBits.bounds 00 
SetRect(dragRect, 4, 24, right - 4, bottom - 4); 
doneFlag := false; 
myWindow := GetNewWindow(windowID, @wRecord, WindowPtr(-1)); 
SetPor t CmyW indow); 
Se tUpWMenus; 
txRect := thePort^.portRect; 
txRect.top := mBarHeight; 
InsetRect(txRect, 3, 3); 
textH := TENewCtxRect, txRect); 


(nain event loop) 

REPEAT 
SystemTask; 
TEIdleC tex tH); 


IF GetNextEventCeveryEvent, myEvent) THEN 
CASE myEvent.what OF 
mouseDown : 
CASE FindWindow(nyEvent.where, whichWindow) OF 

inSysWindow : 
SystemClickCmyEvent, whichWindow); 

inMenuBar : 
IF MenuSelect(myEvent.where) <> 0 THEN 


( handle da menus in the “real” menu bar ) 
inDrag : 
DragWindow(whichWindow, myEvent.where, dra- 
gRect); 
inContent : 
BEGIN 
Global ToLocal (myEvent .where); 
IF myEvent.where.v < mBerHeight THEN 
BEGIN 
IF whichWindow €? FrontWindow THEN 
SelectWindow(whichWindow); 
DoCommand(wMenuSe lect CmyMenuBar , 
myEvent .where)); 
END 
ELSE 
BEGIN 
IF whichWindow O FrontWindow THEN 
SelectWindow(whichWindow) 
ELSE 
BEGIN 
extended := 
BitAndCmyEvent.modifiers, shiftKey) € Ø; 
TEClickCnyEvent . where, 
extended, textH); 
END; ( whichWindow = FrontWindow) 
END; ( click below menu Баг ) 
END; ( inContent ) 
OTHERWISE 


END; ( mouseDown ) 
keyDown, eutoKey : 
BEGI 
theChar := char(BitAnd(myEvent. message, charCode- 
Mask )); 
IF BitAnd(myEvent.modif iers, cmdKey) © 0 THEN 
DoCommand(wMenuKkey(myMenuBar, theChar)) 
ELSE 
TEKeyCtheChar, textH); 
END; { keyDown, autoKey } 
activateEvt : 
BEGIN 
IF BitAnd(myEvent modifiers, activeFlag) © Ø 
THEN 
BEGIN 
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TEActivateCtextH); TYPE WIND 


DisebleItemCmyMenus[editM], undoCommand); , 128 
END wSample 
ELSE 49 50 300 450 
BEGIN Visible NoGoAway 
TEDeact ivateCtextH); 0 
EnebleItem(myMenus (edi tM], undoCommand); 0 
END; ( activate/deactivate ) 
END; (activateEvt ) TYPE MENU 
updateEvt : , 128 
BEGIN M4 


BeginUpdateCWindowPtr(myEvent .message)); 
EreseRectCthePort^ .por tRect2; 


wOr awMenuBar CmyMenuBar 2; TYPE MENU 
TEUpdeteCthePort^.portRect, textH); , 129 
EndUpdateCWindowPtrCmyEvent .message 2; File 
END; ( updateEvt ) Quit/Q 
OTHERWISE 
А ТҮРЕ МЕМ) 
END; ( case event.what of ) , 130 
UNTIL doneF1ag; Edit 
END. CUndo/Z 
тт (- 
* Rmaker source for wSample.rsrc Cut /X 
Copy/C - 
wSample.rsrc Peste/V Pad! 
7777777? Clear TA 
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Pascal Procedures 
Inside Macinkeys 


Fabien Samuel is a mathematics teacher in Paris, as well as 
a convinced Macintosh adept and Programmer. 


Getting Info 

This article is meant to give a comprehensive overview 
about the various resources, structures and procedures involved 
in keyboard events, and especially about the relation between 
Keycodes and Ascii Codes. There has already been a couple of 
very good articles on that subject in MacTutor, and I must thank 
Joel West and Jórg Langowski for the help I found in these as a 
starting point. The presentarticle tries to update and complete the 
information with respect to the new resources in System 4.0 or 
later. 

As an example, I have included the KeyEdDemo applica- 
tion, which allows you to remap your keyboard according to 
specific needs and save that configuration both in RAM, for 
immediate access, and in your system file, so as to keep the 
changes after reboot. This is a very simplified version of my 
shareware application KeyEd 0.5, that features a fully functional 
file menu, multiple scrolling windows, extensive font and view 
options, and advanced error checking. The main purpose of this 
demo version is to show how the resources described below can 
be used. 

The information presented here has been obtained by vari- 
ous means. Lacking documentation about the new resources 
introduced with system 4.0, the 


Fabien Samuel 
Paris France 
MacTutor Vol. 4 No. 12 


translation table contained in KMAP resources. The details of 
this translation are beyond the scope of this article, and in 
everything that follows we will call Key Codes the virtual key 
codes that were so obtained. 

Key Codes can take any value between 0 and 127, not all 
values being actually used (at least until they release a super- 
extended keyboard with 128 keys!). A 16 bytes long variable, 
found in the low-memory global KeyMap ($174), tells which 
keys are down at any given time: each set bit indicating that the 
corresponding key is down. At least 2 normal keys can be thus 
indicated, along with any combination of the modifiers keys 
(Shift, option, etc...). 

The contents of this variable can also be obtained through the 
Pascal procedure GetKeys (TheKeys: KeyMap). A few impor- 
tant notes must be made here. First of all, although the standard 
interface for Type KeyMap is Packed Array [0..127] of Boolean, 
a limitation of the LightSpeed Pascal compiler redefines it as 
Array [0..3] of LongInt. The underlying structure remains the 
same, but it cannot be accessed in the same manner. Second, as 
shown in Figure 1, KeyCodes do not directly correspond to a bit 
offset in the KeyMap variable, the order of bits being reversed in 
each byte. This can be very convenient at the assembly language 
level, where you just need to shift the KeyCode by 3 bits to get 
the byte offset, the remainder being the bit offset within that byte 
that can be used along with instructions like BTST. 


most valuable help was found in |Byte : ‘bit O | m ‘bit 2 КҮ ТТІ lits ‘bite КҮ Byte КТ bit 1 | | bit 2 bit ГТ - bite | m 


MacNosy. I had quite the feeling 
of being a detective, looking 
through the nosied code of INIT 0 
and _KeyTrans to deduce the 
structure of KCHR resources. 
When I finally got Inside 
Mac Vol V, I was able to confirm 


some more information, although 


ди $178 Hin lock 


some of my discoveries and find 6 тата, 2222 СА ГГА 122222 


the information presented there is 
not always very reliable. 


Transitions and Codes 

The keyboard contains its 
own micro-processor, which re- 
turns to the Mac OS Transitions ly, 
Codes, also known as Raw Key 
Codes, every time the user types a 
key. Those Raw Key Codes are 
then translated in Virtual Key 
Codes, involving the use of a 
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Figure 1 


Relation between KeyMap and Key Codes 
KeyCaps from the Extended US ADB Keyboard have been shown along with the 
hex key codes , and the bit offset information. 


O The Definitive MacTutor, Vol. 4 


Things get more complicated in Pascal if one wants to use the 
bit-wise ToolBox utilities, as bits are computed in the reverse 
order (Higher to Lowerbits, Lower to Higher Bytes) than they are 
inthecorresponding assembly instructions. However the follow- 


ing code shows a way to access a KeyMap that will work with any 
compiler: 


Var TheKeys:KeyMap; KeyCode, Offset: Integer; 
GetKeys( TheKeys); 
Offset:= KeyCode + 7 - 2 * (KeyCode mod 8); 


if BitTstC@TheKeys, Offset) then ( Key is down } 


Different KeyBoards 

According to the countries and Mac models, the relation 
between physical keys and their key codes can vary greatly. This 
can be due to distinct physical mappings, for instance the return 
key or the cursor keys can be found at different locations from one 
keyboard to another. To make things even simpler, keys having 
the same function can have different key codes, or, better still, 
keys having the same keycodes can have different meanings! We 
will try to summarize these exceptions in a moment. 

There currently are 6 different Apple keyboards, each one 
having its own keyboard type (Found in low-memory global 
KybdType =$21E - Byte value). However the keyboard types for 
the US classic and Euro classic keyboards are both equal to 3, 
despite their important differences: a way to distinguish between 
them is shown in the demo program (Function GetKbd) . A 
display map of these keyboards can be found in KCAP resources, 
contained in the system file “Key Layout”, that we will discuss 
later. 

In chronological order, the Mac Classic (KybdType = 3) 
keyboards exist in US Version (KCAP ID = 3) and International 
Version (KCAP ID = 259). For archaeologists that might be 
interested, those are the keyboards that were released with the 
antiques 128 and 512 Macs. Then came the Mac Plus keyboard 
(KybdType = KCAP ID = 11), and the 3 ADB Keyboards 
released with the SE and Mac II: Standard (ID= 1), Extended (ID 
= 2) and ISO (ID = 4), this last one satisfying with the interna- 
tional ISO specifications, unlike the Standard ADB 
Keyboard. You can find representations of all those keyboards in 
Figures 2 to 7, along with the corresponding key codes. 

We can now see better what are the main differences 
between keyboards: 

1. Return апа\: Оп ће US Classic Keyboard the keycode for 
Return is $24, whereas on the Euro Classic it is $2A (which maps 


KCRP ID = 5 Е 
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144494796 ле өр қа ле өң ең 
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КСЯР 10 = 5: US CLASSIC KEYBOARD 
Figure 2 
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KCRP 10 = 259 : EURO CLASSIC KEYBOARD 
Figure 3 
to theNcharacter on the US Classic). In all other keyboards, the 
keycode for Return is still $24, and in all cases the ascii code is 
and should be $0D. 

2. Enter and Space: again the corresponding keycodes ($34 
for Enter and $31 for Space on the MacClassic) have been 
inverted on the EuroClassic keyboard. On all subsequent key- 
boards, the Enter key has been moved to the numeric keypad, 
with keycode $4C, the Space key keeping its $31 keycode. 

3. Cursor Keys: originally, those keys were only availableon 
the optional numeric keypad, where they also served as operator 
keys when shifted. With the introduction of the Mac Plus built- 
in numeric keypad, the cursor keys were moved to the main 
keyboard, while the numeric operator keys stayed where they 
belonged on the keypad. The only problem is that they kept the 
same keycodes! To solve this conflict, when you type one of the 
numeric operator keys on the Plus, it acts as if you had held the 
shift key down (and likewise, holding down the shift key while 
typing one of the cursor keys will return the corresponding 
numeric operator). On subsequent models, this conflict was 
resolved by giving altogether different keycodes to both the 
numeric operator and cursor keys: this means 8 new key codes 
have been introduced for that purpose. The situation is summa- 
rized in Figure 8. Also note that the + and - keys on the keypad 
have been inverted between the ADB extended and standard 
keyboards. 

The main conclusion of all this is that you should only rely 
on the ascii code of such control characters, which always keeps 
the same value whatever keyboard you use. 


Keyboard Events 
For most purposes, dealing with keyboard input mainly 
involves polling KeyDown and AutoKey events. Information 
about such an event is given in the Message and Modifiers fields 


ме | — 
е оозана а : 
grossis im rm sans 


Asse —Ç 
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КСЯР ID = 11 : МЯС PLUS KEYBOARD 


Figure 4 
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экы : 
PL А : 


KCRP 10 = 1: 


ADB STANDARD KEVBORRD 

Figure 5 
of the EventRecord returned by GetNextEvent. The Message 
field has the following 4 bytes long structure: 

«Reserved, ADBAddress, keycode, ascii code» 

ADBAddress is used with the Mac SE and II, and contains 
areference number of the keyboard the typing came from, useful 
if various keyboards are simultaneously connected (see January 
88 MacTutor for an example of this). Ascii code is obtained 
through the conversion routines that are discussed in the next 
paragraphs, taking into account both the key code and the state of 
modifiers keys. 

The Modifiers field of the EventRecord is made up of 2 
bytes, the high byte giving the state of the modifiers keys in the 
following bit-arrangement: 

<x,y,z,control,option,caps lock,shift,command> 

Flags x,y and z are normally zero. However, the extended 
ADB keyboard can be reconfigured so as to distinguish between 
the left and right Shift,Option and Control Keys. In that case, the 
right keys will generate new key codes, and flags x,y,z could be 
renamed: R.Control,R.Option,R.Shift. This possibility is sup- 
ported in order to use the Mac with an operating system Inside 
Mac doesn’t dare to mention, so neither will I! It can be imple- 
mented through the use of the ADB operators mechanism, which 
might be the subject of another article. Anyway, this capacity is 
strongly discouraged because it doesn’t comply with the User 
Interface. 

Finally, let’s note that some keys do not immediately return 
an event: those are the keys that are used in conjunction with 
another key to produce exotic objects like accented characters. I 
will refer to them as “Double Strike Keys”, also the official 
terminology appears to be “Dead Keys”, but I just don’t like the 
idea of my keys being dead! 


In the beginning, there was INIT 0 and 1... 


KCAP 1D = 2: ADB EXTENDED KEYBOARD 
Figure 6 
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On the first Macs, and until the Mac Plus with systems 3.x, 
all the information related to converting key codes to ascii codes 
was contained in system resources INIT 0 and 1. The Localizer 
was in charge of adapting these resources according to the 
various countries. Those resources contained both the conver- 
sion code and the associated translation tables. 

With systems 4.x and later, The INIT’s now mainly contain 
code, the translation tables being now separate and contained in 
the KCHR 0 system resource. At boot time, the INIT’s are loaded 
into the system heap and jumped to. They are mainly in charge 
of installing pointers to the conversions routines in low-memory 
globals Key1Trans and Key2Trans. 

The reason for there being two separate routines is due to the 
fact that originally, the numeric keypad was optional. Key1 Trans 
will thus deal with keycodes from Oto 63, while Key2Trans treats 
keycodes from 64 to 127, that used to be found exclusively on the 
numeric keypad. This distinction now appears completely artifi- 
cial (if not intelligent...) since the Mac Plus was introduced. It 
seems that those routines have only stayed for compatibility 
reasons, as their codes are now almost the same, and both refer 
to the new _KeyTrans ToolBox trap, which does most of the 
work. 


The Inner Workings 
To start with, I will describe the main steps involved in INIT 
0, INIT 1 having a similar functionality. As any INIT resource, 
it gets executed at boot time after being loaded as a locked 
relocatable block, accessed through a handle. It’s made up of two 
essential routines that I'll call SetUp and Key1TransMain. SetUp 
is the part that gets jumped to at boot time and does the following 


1. Load KCHR 0 into the system heap, if it's not already 
there. 

2. Create а non-relocatable copy of KCHR 0 in system heap 
and store a pointer to it at offset 14 in a parameter block that is 
accessed through the pointer maintained in BasicGlob (= $2B6) 
low-memory global. Actually, this copy is expanded by at least 
512 bytes, probably in order to allow its modification by another 
program. 

3. Copy Byte 6 from the itlc O in a Data zone internal to INIT 
0. This is an international utilities resource, and the value of this 
byte will be used to distinguish between the US Classic and Euro 
Classic keyboards, as illustrated in the GetKbd function of the 


= demo program. This actually must mean that run- 
ning with an Euro Classic keyboard and a US 
system would make believe the keyboard was US 
[This is true, recalling all the mixups we had using 
different systems - JL]: there doesn't seem to be a 
hardware method to distinguish between the two 
keyboards. 

4. Put the entry point to Key1TransMain in 
low-memory global Key1Trans. 

5. Cut down the size of its own handle before 
returning, the SetUp routine being now useless 
(this is accomplished by putting those last instruc- 
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Figure 7 
tions at the beginning of the block, unless one wants to call this 
the Auto-Destroy routine!). 


Key1Trans 

KeyltransMain is the part currently used every time a 
keydown or keyup event is detected by the Event Manager. This 
is a register-based routine, and calling it from an high level 
language involves assembler glue-code (see the Demo Program). 
It takes on entry: 

D2 contains the keycode (less than 64, or nothing will 
happen: in that case one must call Key2Trans) 

БІ contains the state of the modifiers keys (as it appears іп 
the third word of the KeyMap structure: this differs from the 
EventRecord Modifiers field). 

D3 should be 0 for most purposes: bit 7 can be set to indicate 
that the event should be treated as a key-up event rather than a 
key-down event. 

On exit, DO contains the resulting ascii code. 

This routine works as follows: 

1. Make up a word that has the following structure: 

- the high byte contains the modifier flags as they would 
appear in the EventRecord modifiers field: 

«x,y,Z,ctl,opt,caps,shift,cmd» 

Note that the command key state is read directly on the 
keyboard when the routine is executed, and so doesn't depend on 
the one you pass in D1. 

- the low byte contains the key code, with a flag in bit 7 
indicating KeyUp status. 


= |= агь |= Tenn 
өе [== 
| 
е еее 
eee eee 


Figure 8 
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2. Call the ToolBox function 

KeyTrans (transData:Ptr; KeyCode:Integer; 
VAR State: LongInt): Longint; 

where KeyCode is the word obtained in step 
1, TransData a pointer to the copy of KCHR 0 
accessed through BasicGlob as described above, 
and State an offset used for double strike keys that 
is maintained at offset 10 in the parameter block 
pointed to by BasicGlob. We will see how this 
works in just a moment . 

The function result contains in its Low Word 
the ascii code of the current key, taking into 
account its possible combination with a previous double strike 
key. The High Word returns the ascii code for an eventually 
waiting double strike if it couldn't be combined with the current 
key. 

3. In case the High Word is non-zero, Key1Trans will post 
an event for it, thus causing the default ascii value of the previous 
double strike to be reported before that of the current key. 

4. In any case, the ascii code for the current key and 
modifiers is returned in DO. 


KeyTrans and KCHR 0 

What finally remains to complete this overview is to under- 
stand how the KeyTrans function is working. In order to do that, 
we first need to know the structure of the KCHR 0 resource, 
which will incidentally give us the means to modify it. 

As I said, KCHR 0 is the fundamental resource that allows 
to translate a keycode, along with the associated modifiers, to a 
standard ascii code. 

1. The first word of a KCHR resource presently contains 
zero, and doesn't seem to be currently used. 

2. The next 256 bytes serve as a kind of offset table, each one 
containing a block number used as follows: the high byte of the 
Event Record modifiers field can theoretically take any value 
between 0 and 255, assuming the right modifiers keys are acti- 
vated. This value serves as an offset into the table to get the 
corresponding block number. Each block is 128 bytes long, and 
contains the mapping for every key code when typed along with 
the above modifiers. 

3. The following word contains the actual number of blocks 
that are used (currently 8, numbered from O to 7). This means 
different modifiers combinations can lead to the same block. 

4. Then come the block themselves, each of its 128 bytes 
giving the ascii code for the corresponding key code, which 
serves as an offset into the block. If the ascii code is zero, it means 
175 either a double strike key, a modifier key, or no key at all. 

5. Finally, we find a variable length part that deals with ` 
double strikes. 

а) The first word contains the total number of double strike 
keys. 

b) For each one of them, we find a structure organized as 
follows: 

b1) 2 bytes, giving the block number and key code of that 
double strike. 
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b2) Word giving the total number of associated variants. 

b3) List of all those variants in the form: Current Ascii Code 
/ Resulting Ascii Code 

b4) Word giving the default ascii value of that double strike, 
incase the current ascii code wouldn't combine with it to produce 
a resulting ascii code. 


Let's give an example to try and make things a bit clearer: on 
the US keyboard, Option E followed by E results in the accented 
Character 6, but if followed by P it will result in the two 
consecutive characters “p. The keycode for E is SE, while the 
option key gives a value of 8 to the modifiers flags high byte. 
Counting from zero, byte number 8 in the block numbers table 
has a value of 3, which leads us to block number 3. Looking at 
byte number $E in that block, we see that its value is zero! This 
confirms us in thinking that Option E is a double strike. Now, 
let’s look at the list of double strike keys: the first of them is 
precisely the one we want: Block Number = 3, KeyCode = $E. 
The next word tells us 7 variants are associated with it, and among 
them we find the variant $65,$8F: ascii code $65 (Character e) 
thus combines with our double strike to produce ascii code $8F 
(Character 6). On the other hand, no variant is associated with 
ascii code $70 (Character p), and it will thus be the default value 
$60 (^ accent) that will be returned, followed by the character р. 

We finally can explain how the KeyTrans function does its 
trick. The Modifiers byte is used as an offset into the block 
numbers table, while the keycode byte serves as an offset into the 
designated block. If the ascii code it finds at the designated 
position is non-zero, KeyTrans just returns with it. If it is zero, 
KeyTrans looks into the double-strike table and tries to match the 
BlockNumber/Keycode combination with one in the list. If it 
succeeds, the State variable is loaded with the byte offset between 
the start of the first block and the location of the “number of 
variants” entry associated with that double strike. In all other 
cases, State will be cleared. When KeyTrans is called again, and 
State is non-zero, it assumes there’s a pending double strike and, 
after getting the current ascii code, it will look right away at the 
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designated offset to find a match between the current ascii code 
and an eventual resulting ascii code. If it finds one, it returns with 
the resulting ascii code. Otherwise it returns with the current ascii 
code in its low word, and the default ascii code of the pending 
double strike in its high word. In the last case, and if it has been 
called by Key1Trans, Key1Trans will post the appropriate event 
as described above. We can thus see how important it is to 
maintain the value of State between calls to KeyTrans if we want 
to get double strikes responses. 

As a final point, note that KeyTrans actually does some pre- 
processing related to the Script Manager. 


The Demo Program 

The following LightSpeed Pascal program tries to give a 
simple example of how all this stuff can be put to use. It needs 
system 4.0 or later to run. It only allows editing of normal keys, 
and I left out all memory and resources error checking in order to 
keep it as short as possible. Note that the Shareware version 
KeyEd 0.5 does implement advanced error-checking features. 
I'll leave it as an exercise to the reader to check for Nil Handles 
and call MemError or ResError when appropriate. However, I 
couldn’t resist showing how the KCAP’s resources mentioned 
above can be used in giving a graphical interface to keyboard 
editing, and that accounts fora large part of the program code. So 
I first have to say a word about their structure (obtained once 
again by nosying the КеуСар DA): 

1. Window Rectangle 
2. KeyCaps DA TextEdit view rectangle 
3. Number of different key shapes 
4. For each shape: 
a) Number of points used to define it, minus 1. 
b) List of those points. 
c) Number of associated keys, minus 1. 
d) List of those keys in the form: 
«KeyCode, Vertical Offset, Horizontal Off- 
seb. 

The points define a region made up of rectangles, that will 
then be offset to the adequate position for each consecutive key. 
Note that the keycode field actually contains additional informa- 
tion, so I take it modulo 128. The procedure MainCaps that runs 
through this structure shows you type-casting in Pascal can do 
wonders, but would evidently be more elegant in assembly! The 
only thing I wasn't able to do with type-casting was to access a 
byte at a time in memory, so I wrote the short assembly routines 
Peek and Poke for that purpose, the names being a tribute to Basic 
programmers. 

The program also shows an example of using procedural 
parameters, a most convenient feature of the LSP compiler. This 
way the region obtained in MainCaps can be used either for 
drawing the key or for dealing with a click inside it, or for any 
other purpose you might want. However, if you want to port that 
program to another compiler, you'll need to implement a Case 
statement within MainCaps to achieve the same result. 

Finally, the program also shows the use of a modeless dialog 
with an User Item. The user procedure UserDraw is attached to 
that item with the SetUserProc procedure. The Dialog Manager 
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will call it automatically on each update event for the dialog 
window, and it is in charge of drawing the keyboard. Likewise, 
if there was a click in that User Item rectangle, we call MainCaps 
to find if it was in a key, and handle the event accordingly in the 
ActiveClick procedure. Note that although the Dialog Manager 
deals with mouse-down events when the Dialog Window is 
active, you still have to explicitly activate it by calling Select 
Window when the Event Manager reports a click in the contents 
region. You also have to pre-process keydown events, to filter out 
command key equivalents and any other typing you don't want 
passed to the edit field. One important warning if you use 
LightsBug while running this program is that if you inadvertently 
click in your switched-out Dialog Window, LSP 1.11 will bomb 
after displaying the usual “You can only drag your program's 
windows while itis halted" message. This could be due to the fact 
that LSP gets notified of the event only after the Dialog Manager 
has tried to run your User Proc, which will rely on globals that 
have become invalid since your program is switched out. Any- 
way, I nearly got my hard-disk trashed while trying to figure out 
the problem! 

Note that the RMaker source file for the program doesn't 
include definitions for the KCAP resources used by the program. 
Soafter compiling this file with RMaker, you should use ResEdit 
to copy these resources from the Key Layout file in your system 
folder and paste them into your resource file. While you're at it, 
you could also install BNDL or SIZE resources to make the 
program look more fancy. It should run at ease under a 50K 
partition. There are many more possible improvements, but ГИ 
leave them to your imagination. 


Listing: 
PROGRAM KeyEdDemo; 


( copyright F.Samuel and MacTutor 1988 } 
| |, only with system 4.х ог later ) 
%- 


KeyEdDeno . pas 


{ turn off automatic initialization } 
($L keyEdDemoRes) 
( load resource file ) 


CONST 
DialogID - 128; 
EditCodeItem = 2; 
LoadBtn - 5; 
UserItem - 6; 
AsciiCherItem = 7; 
KeyCodeItem = 8; 
AboutAlrt = 129; 
LoadAirt = 130; 
AppleID ғ 1; 
AboutItem = 
FileID - 2; 
EditID = 3; 
CutItem = 3; 
CopyItem = 4; 
Pasteltem = 5; 
ClearItem = 6 


1; 
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( Low-memory globals ) 
KybdType = $21E; 
ScsiFlag = $822; 
KeylTrans = $29E; 
BasicGlob = $2B6; 
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( KCaps ID of various keyboards ) 
MacPlusKbd = 11; 
MacClessicKbd = 3; 
EuroMacKbd = 259; 

ADBKbd = 1; 
ADBExtKbd = 2; 
ADBIsoKbd = 4; 


TYPE 
Prect = “Rect; ( for type-casting a pointer ) 
Рі опа = ^LongInt; 
PWord = “integer; 
PPoint = “Point; 


VAR 
Finished, EditOn : 
DragRect : Rect; 
MouseLocal : Point; 
KCapsHandle, KChrHandle 
DemoDialog : DialogPtr; 
HiliteKeys : SET OF 0.. 127; 
EditKey, EditModifs : Integer; 


Boolean; 


: Handle; 


( utilities to acces properties of items in a dialog } 


PROCEDURE SetDItemText (TheDialog : DialogPtr; 


TheItem : Integer; 
TheText : Str255); 
VAR 
ItemType : integer; ( should be а text item ) 


ItemHandle : Handle; 
DispRect : Rect; 
BEGIN 
GetDItem(CTheDialog, TheItem, ItemType, ItemHandle, 
DispRect); 
SetITextCItemHandle, TheText) 
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FUNCTION GetDItemText CTheDialog : DialogPtr; 
TheItem : Integer) : Str255; 
VAR 
ItemType : integer; ( should be а text item ) 
ItemHandle : Handle; 
DispRect : Rect; 
TheText : Str255; 
BEGIN 
GetDItem(TheDialog, TheItem, ItemType, ItemHandle, 
DispRect); 
GetITextCItemHendle, TheText); 
GetDItemText := TheText 
END; 


FUNCTION GetDItemRect (TheDialog : DialogPtr; 
TheItem : Integer) : Rect; 
VAR 
ItemType : integer; 
TtemHandle : Handle; 
DispRect : Rect; 
BEGIN 
GetDItemCTheDialog, TheItem, ItemType, ItemHendle, 
DispRect); 
GetDItemRect := DispRect 


END; 
PROCEDURE SetUserProc (TheDialog : DialogPtr; 
TheItem : Integer; 
TheProc : ргосРіг); 
VAR 
ItemType : integer; ( should be an UserItem ! ) 


ItemHandle : Handle; 
DispRect : Rect; 
BEGIN 


GetDItemCTheDialog, Тһе (еп, ItemType, ItemHandle, 
DispRect); 
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SetDItemCTheDialog, TheItem, ItemType, HandleCtheProc), 
DispRect) 
END; 


( function NumToString , more convenient that way ... ) 


FUNCTION FNumToString (TheNum : LongInt) : Str255; 
VAR 
TheString : Str255; 
BEGIN 
NumToStringCTheNum, TheString); 
FNumToString := TheString 
END; 


st, 


interface for external! procedures and functions : ) 


FUNCTION KeyTrans (transData : Ptr; 
Кеусоде : INTEGER; 
VAR state : LONGINT) : LONGINT; 
INLINE 
$49C3; 


PROCEDURE poke Caddress : longint; 
value : integer); 
external; ( puts low byte of value at address ) 


FUNCTION peek (address : longint) : integer; 
external; ( returns byte at address ) 


FUNCTION Key12Trans (KeyCode, KeyModifs : Integer) : 
Integer; 
external; 


( Pascal procedures and functions follow ... ) 


FUNCTION GetAscii (KeyCode, Modifs : integer; 
VAR Ascii : integer) : Boolean; 
( Returns true if it's а normal key , Ascii returns escii 
code even if it’s а double strike) 
VAR 
State : LongInt; 

BEGIN 
State 
Ascii 

State)); 
IF Ascii = 0 THEN 
BEGIN 
GetAscii := false; 
Ascii := LoWord(KeuTrans(KChrHandle*, KeyCode + 
Modifs, State)) 
END 


ELSE 
GetAscii := true 


LoWord(KeyTrensCKChrHandle^, KeyCode + Modifs, 


END; 


FUNCTION GetKbd : Integer; 
( one KCAP ID of current keyboard } 
A 
TempID : integer; 
addr : Plong; 
SCSIMac : boolean; 
BEGIN 
TempId := peek(KybdType); 
SCSIMac := BitTst(Ptr(SCSIFlag), 5); 
IF (МОТ SCSIMac) AND CTempID © MacPlusKbd) THEN 
BEGIN 


tempId := MacClassicKbd; 
addr := Plong(Key!Trans); 
IF peekCaddr* + 10) © Ø THEN ( test itlc byte } 
TempId := EuroMacKbd 
END; 
GetKbd := TempID 
END; 
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PROCEDURE SetUpMenus; 
VAR 


ID : integer; 
BEGIN 
FOR ID := AppleID TO EditID DO 
InsertMenuCGetMenuCID2, 02; 
AddResMenu(GetMHandleCAppleID), ‘DRVR’); 
DrawMenuBar 
END; 


PROCEDURE MainCaps (PROCEDURE treatIt (гоп : RgnHendle; 
Code : integer)); 
VAR 
Hrgn : RgnHendle; 
addr : PWord; 
Paddr : PPoint; 
NumRgn, NumRect, NumKeys, i, j : integer; 
Keycode, dh, dv : Integer; 
TL, BR : point; 
KRect : rect; 
BEGIN 
BEGIN 
SetPort(DemoDialog); 
GetMouse(MouseLocal ); 
ClipRectCDemoDialog^.PortRect?; 
Hlock(KcapsHandle); 
Addr := Pword(Ord4(KcapsHandle*) + 16); 
NumRgn := Addr^; 
IF NumRgn › 0 THEN 
FOR i := 1 TO NumRgn 00 
BEGIN 
Addr := PwordCOrd4CAddr) + 2); 
NumRect := eddr^; 
Hrgn := NewRgn; 
OpenRgn; 
SetPtCTL, 0, 0); 
Addr := PwordCOrd4CAddr) + 2); 
FOR j := В TO NumRect 00 
BEGIN 
PAddr := PPoint(addr); 
BR := Paddr*; 
Pt2RectCTL, BR, Krect); 
FrameRect(Krect); 
TL := BR; 
Addr := PwordCOrd4CAddr) + 4); 
END; 
CloseRgnCHrgn?); 
NumKeys := eddr^; 
FOR j := 0 TO NumKeys 00 
BEGIN 
Addr := Pword(Ord4CAddr) + 2); 
KeyCode := eddr^; 
Addr := PwordCOrd4CAddr) + 2); 


dv := eddr^; 
Addr := Pword(Ord4(Addr) + 2); 
dh := addr’; 


OffsetRgnCHrgn, dh, dv); 
TreatIt(Hrgn, Keycode MOD 128); 


END; 
DisposeRgn(Hrgn?; 
END; i 
Hunlock(KcapsHand]e) 
END 
END; 


PROCEDURE InvertKey (Rgn : RgnHandle); 
VAR 
InnerRgn : RgnHendle; 
N 


InnerRgn :- NewRgn; 
CopyRgn(Rgn, InnerRgn); 
InsetRgnCInnerRgn, 2, 2); 
InvertRgnCInnerRgn); 
DisposeRgnCInnerRgn? 
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END; 
PROCEDURE DrawKey (гоп : RgnHandle; 


Code : integer); 

VAR 
DrewRgn : RgnHandle; 
AsciiCode : Integer; 
NormalKey : boolean; 

BEGIN 
FrameRgn(Rgn); 
DrewRgn := NewRgn; 


CopyRgn(Rgn, DrawRgn); 
InsetRgn(DrawRgn, 1, 1); 
SetClipCDrawRgn); 
EraseRgn(DrawRgn); 
NormalKey := GetAscii(Code, EditModifs, AsciiCode); 
WITH DrewRgn^^.rgnBBox DO 
MoveToCleft + 1, bottom - 2); 
DrawChar (Chr CAsci iCode 2); 
DisposeRgn(DrawRgn); 
IF Code IN HiliteKeys THEN 
Inver tKey(Rgn); 
ClipRect(DemoDialog* .PortRect) 
END; 


PROCEDURE UserDraw (TheWindow : 
ItemNum : 


WindowPtr; 
Integer); 
VAR 
FillPat : Pattern; 
TheRect : Rect; 
BEGIN 
TheRect := GetDItemRect(DemoDialog, ItemNum); 
GetIndPattern(FillPat, 0, 10); 
FillRectCTheRect, FillPat); 
FrameRect(TheRect); 
MainCaps(DrawKey ) 
END; 


PROCEDURE InitThings; 
VAR 


i, Error : Integer; 

BEGIN ( Get KybdID and KCaps ; 
FlushEventsCEveryEvent, 0); 
InitGraf C@ThePort); 
InitFonts; 

Ini tWindows; 
InitMenus; 
TEInit; 
InitDialogsCNIL); 
InitCursor; 
SetEventMask(EveryEvent - KeyUpMask); 
MaxApp1Zone; 
FOR i := 1 TO 5 DO 

MoreMasters; 
WITH ScreenBits.Bounds 00 

SetRect(DragRect, left + 4, top + 24, right - 4, bottom 


SetUserProc;Show dialog } 


- 4); 
SetUpMenus ; 
KCapsHandle :- GetResource(‘KCAP’, GetKbd); 
DetachResource(KCapsHandle); ( don’t let а DA release it 
on your back ! } 

KChrHendle := GetResourceC'KCHR^, 0); 

Error := HandToHand(KChrHandle); ( make а copy , so we can 
modify it ) 

MoveHHiCKChrHandle); ( keep heap unfragmented ) 

HLockCKChrHandle); 

HiliteKeys := [1]; (по keys to hilite until the user 
selects one ) 

EditModifs := 0; 

rm := False; ( wait for the user to select а key to 
edit 

DemoDialog := GetNewDialog(DialogID, NIL, WindowPtr(-1)); 

SetUserProc(DemoDialog, UserItem, @UserDraw); 

ShowWindowCDemoDialog); 
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Finished :- False 
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PROCEDURE DoMenu (Code : 
VAR 
MenuNum, ItemNum, Temp : integer; 
DeskAccName : str255; 
BEGIN 
IF code € 0 THEN 
BEGIN 
MenuNum := HiWord(Code); 
ItemNum := LoWord (Code); 
CASE MenuNum ОҒ 
AppleID : 
IF ItemNum = AboutItem THEN 
Temp := Alert(AboutAlrt, NIL) 
ELSE 
BEGIN 
GetItemCGetMHandleCAppleIDO, ItemNum, 


longint); 


DeskAccName); 
Temp :- OpenDeskAccCDeskAccName); 
END; 
FileID : 
Finished := True; 
EditID : 
IF NOT SystemEditCItemNum - 1) THEN 
IF CFrontWindow = 
CASE ItemNum OF 
CutItem : 
DigCut(DemoDialog); 
CopyItem : 
DigCopy(DemoDialog); 
Pasteltem : 
DigPaste(DemoDialog); 
CleerItem : 
DigDeleteCDemoDialog); 
OTHERWISE 
END; 
OTHERWISE 
END; 
HiliteMenu(0) 
END 


END; 


PROCEDURE StartEdit (KeuCode, AsciiCode : Integer); 
( enable editing the ascii code of the selected кеу ) 
BEGIN 
EditKeu := KeuCode; 
HiliteKeys := HiliteKeys + [EditKeu]; 
SetDItemTextCDemoDialog, EditCodeItem, 
FNumToStringCAsci iCode2); 
SellText(DemoDialog, EditCodeItem, 0, MaxInt); 
SetDItemTextCDemoDialog, KeyCodeItem, 
FNunToStr ingCEdi tKey2); 
SetDItemText(DemoDialog, AsciiCharItem, ChrCAsciiCode)); 
EditOn := true 
END; 


PROCEDURE DrewEditKRgn (Rgn : RgnHendle; 
TheCode : Integer); 
( update key contents in case it chenged ) 
BEGIN 
IF TheCode - EditKey THEN 
DrawKey(Rgn, EditKey) 
END; 


PROCEDURE ValidateEdit; 
( validate user editing of the selected key } 
VAR 


BlockNumber : Integer; 
MapAddress, NewAsciiCode : LongInt; 
BEGIN 
IF EditOn THEN 
BEGIN 


DemoDialog) AND EditOn THEN 
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StringToNum(GetDI temText(DemoDialog, EditCodeltem), 
NewAsci iCode); 

MapAddress := Ord4(KChrHandle*); 

BlockNumber := Peek(MapAddress + BitShift(EditModifs, 
-8) + 2); 

Poke(MapAddress + 260 + BlockNumber * 128 + EditKey, 
NewAsci iCode); 

EditOn := False; 

SetDItemTextCDemoDialog, EditCodeItem, ‘’); 

SetDItemTextCDemoDialog, KeyCodeItem, ””); 

SetDItemTextCDemoDialog, AsciiCharItem, “”); 

HiliteKeys := HiliteKeys - [EditKeu]; 

MainCaps(DrawEdi tKRgn); 

END 
END; 


PROCEDURE CodeXORModifs (ModifCode : Integer; 
VAR Modifs : Integer); 
( XOR new modifier with the already selected ones ) 
VAR 
TempModifs : Integer; 
GIN 
TempModifs := 0; 
BitSetCeTempModifs, $3E - ModifCode); 
Modifs := BitXor(Modifs, TempModifs) 
END; 


FUNCTION EditPerm (KeyCode, Modifs : 
VAR AsciiCode : 
( cen thet key be edited ? ) 
BEGIN 
IF GetAsciiCKeyCode, Modifs, AsciiCode) THEN 
EditPerm := true 
ELSE ( check that it’s not а double strike nor а modif ier 


Integer; 
Integer) : Boolean; 


EditPerm := (AsciiCode = Ø) AND NOT (KeyCode IN 
[$3C. .$3E1) 
END; 


PROCEDURE ActiveClick (гоп : RgnHandle; 
Code : integer); 
VAR 
AsciiCode : 
BEGIN 
IF PtInRgn(MouseLocal, Коп) THEN 
IF (Code <> EditKey) OR NOT EditOn THEN 
BEGIN 
ValidateEdit; 
IF Code IN ($37..$38] THEN ( modifier key was 


BEGIN 
CodeXORModifs(Code, EditModifs); 
IF Code IN HiliteKeys THEN 
HiliteKeys := HiliteKeys - [Code] 
ELSE 
HiliteKeys := HiliteKeys + [Code]; 
IF EditPermCEditKey, EditModifs, AsciiCode) 


Integer; 


clicked ) 


THEN 
StartEdit(EditKey, AsciiCode); 
MainCaps(DrawKey) ( redraw the keyboard to 
update hiliting } 
END 


ELSE IF EditPermCCode, EditModifs, AsciiCode) THEN 
BEGIN 


InvertKeu(Rgn); ( hilite it , and let user edit 
it | 
StartEdit(Code, AsciiCode) 
END 
END 
END; 


FUNCTION CheckSysTrans (TransData : Ptr) : Boolean; 
( is TrensData really а pointer to the system mapping table 
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VAR 
KeyCode, AsciiCode : 
BEGIN 
CheckSysTrans := true; 
FOR KeyCode := 0 Т0 16 00 
BEGIN 
AsciiCode 
compute it } 
IF PeekCOrd4CTrensData) + 268 + KeyCode) € AsciiCode 


Integer; 


:= Keyl2Trans(KeyCode, 0); ( let system 


THEN 
CheckSysTrans :- False; ( compare with our table ) 
IF AsciiCode = 0 THEN 
BEGIN 
AsciiCode := Key12Trans(KeyCode, Ø); 
FlushEventsCEveryEvent, Ø) ( double strike may 
have posted әп event , flush it ) 
END 


END 
END; 


FUNCTION GetSysTrans (VAR TheTrans : Ptr) : boolean; 
VAR 


BGlob, Addr : PLong; 
BEGIN 
Bglob := PLong(BasicGlob); 
Addr := PLong(BGlob* + 14); 
( not documented , so better check if we can rely on it ! ) 
TheTrans := Ptr(Addr^); 
GetSysTrans := CheckSysTrens(TheTrans) 
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PROCEDURE DoLoad; 
VAR 
TheSize : LongInt; 
RamTransPtr : Ptr; 
SysKchr : Handle; 


AppResFile : integer; 
BEGIN 
IF AlertCLoadAirt, NIL) = Ok THEN 
BEGIN 
TheSize := GetHendleSizeCKChrHandle); 


IF GetSysTrans(RamTransPtr) THEN ( see above ... ) 
BlockMoveCKChrHandle^, RamTransPtr, TheSize); 
AppResFile := CurResFile; 
UseResF ileC2); 
SysKchr := GetResource(‘KCHR’, 0); 
BlockMoveCKChrHandle^, SysKChr^, TheSize); 
ChangedResource(CSysKChr 2; 
UpdateResF 11е(0); 
UseResF i leCAppResF ile) 
END 
END; 


PROCEDURE DoDialog CTheEvent : EventRecord); 
CONST 
Enter = $03; 
Return = $00; 
VAR 
TheDialog : DialogPtr; 
ItemHit, CharCode : Integer; 
PassIt : Boolean; 
BEGIN 
WITH TheEvent DO 
IF What = KeyDown THEN 
BEGIN ( filter key down events ) 
CharCode := BitAnd(Message, CharCodeMask ); 
PassIt := False; 
IF BitAnd(Modifiers, CmdKey) € 0 THEN 
DoMenuCMenuKeyCChr (CharCode ))) 
ELSE IF EditOn THEN 
IF CharCode IN (Return, Enter] THEN 
ValidateEdit 
ELSE 
PassIt := True 
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ЕМО 
ELSE 
PessIt := True; 
IF PassIt THEN 
IF DialogSelect(TheEvent, TheDialog, ItemHit) THEN 


;MDS Glues for Pascal Peek and Poke 
¿Procedure poke(Caddress :ptr; value: byte) 
¿function peekCaddress:ptr): byte; 


CASE ItemHit OF 
UserItem : 
MainCaps(ActiveClick); 
LoadBtn : 
DoLoad; 
OTHERWISE 
END 
END; 


PROCEDURE MainLoop; 
VAR 
GotEvent : Boolean; 
TheEvent : EventRecord; 
TheWindow : WindowPtr; 
BEGIN 
SystemTask; 
GotEvent := GetNextEvent(EveryEvent, TheEvent); 
IF IsDialogEvent(TheEvent) THEN 
DoDialog(TheEvent) 
ELSE IF GotEvent THEN 
WITH TheEvent DO 
CASE What OF 
MouseDown : 
CASE FindWindowCWhere, TheWindow) OF 
inMenuBar : 
DoMenuCMenuSelectCWhere)); 
inSysWindow : 
SystemClick(TheEvent, TheWindow); 
inContent : 
IF TheWindow € FrontWindow THEN 
SelectWindowCTheWindow); 
inDrag 


inGoaway : 
IF TheWindow € FrontWindow THEN 
SelectWindowCTheWindow) 


ELSE IF TrackGoAway(TheWindow, Where) THEN 


Finished := True; 
OTHERWISE | 
END; 
KeyDown : 
IF BitAnd(Modif iers, CmdKey) © 8 THEN 


DoMenu(MenuKey(Chr(BitAnd(Message, CharCode- 


Mask )))); 
UpdateEvt : 
BEGIN ( just in case ... } 
TheWindow := WindowPtr(Message); 
BeginUpdate(TheW indow); 
EndUpdate( TheWindow) 
END; 
OTHERWISE 
END 
END; 
BEGIN 
InitThings; 
REPEAT 
MainLoop 
UNTIL Finished 
END. 


Listing: KeyEdDemo.asn 


,MDS source code for KeyEDDemo External procedures 
,copyright F.Samuel and Mac Tutor 1988 

; АГ{ег compiling , turn the .rel file into a LSP 

; library using rel.Converter , then include the Тір 
; into your LSP project 
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DragWindow(TheWindow, Where, DragRect); 


XDEF peek 

XDEF poke 

value EQU 8 

addr 1 EQU 10 

poke 
LINK Аб, #0 
MOVEA.L addr 1(Аб), Ad 
MOVE value(CA6),D0 
MOVE.B 00, (АЙ) 
UNLK Аб 
МОУЕА. (SP)*,A0 
ADDQ.L 86 SP 
JMP (AQ) 

addr2 EQU 8 

result EQU 12 

peek 
LINK Аб, 80 


; Function Key 12Trans(KeyCode, KeyModifs: Integer ) 


we `. 


MOVEA.L addr2(A6), Аб 
MOVEQ 80,00 

MOVE.B (Аб), DØ 

MOVE DØ resul + (Аб) 


UNLK A6 


MOVEA.L CSP)+ AØ 
ADDQ.L #4, SP 


JMP (A0) 


: Integer; 


KeyModifs are as they appear in the third word of KeyMap 
Function returns AsciiCode 


XDEF Key 12Trans 
Key 1Тгапз EQU $29Е 
Key2Trans EQU $2A2 
KeyModifs EQU 8 
KeyCode EQU 19 
FunRsit EQU 12 
Key 12Тгапв 
LINK Аб, t 
MOVEM.L A0/D90-D3, -CSP) 
MOVE KeyCodeCA6), D2 
MOVE KeyModifsCA62,D1 
MOVEQ 80,03 
CMP I 864,02 
BHS.S ёі 
MOVEA.L Key 1Trans , Ad 
BRA.S e2 
6 1M0VEA.L Key2Trans, Аб 
82 JSR (Аб) 
МОУЕ D9,FunRs1tCA6) 
MOVEM.L (SP2*,A0/D0-D3 
UNLK Аб 
MOVEA.L (SP)+,A0 
ADDQ.L 84 SP 
JMP (AQ) 
Listing: KeyEdDemoRes.R 


* KeyEdDemo resource definitions for RMaker * 
* Copyright 1988 - F.Samuel end Mac Tutor 
* After compiling , don’t forget to add the * 
ж KCAP resources from Key Layout in your 
* System Folder , using ResEdit 


* include the file into your LSP project * * 2 
х using Run Options from the Project Menu * EditText Disabled 
5 96 25 133 
KeyEdDemoRes 
x 3 
Type MENU StatText Disabled 
5 279 25 357 
‚1 Кеу Соде : 
\14 
About KeyEdDemo X 4 
(- StetText Disabled 
5 144 25 221 
,2 Ascii Char : 
File 
Quit/Q * 5 
BtnItem Enabled 
,3 5 418 25 478 
Edit Load 
Undo/Z 
(- * 6 
Cut /X UserItem Enabled 
Copy/C 32 5 222 482 
Paste /V 
Clear x 7 
StatText Disabled 
Type DLOG 5 223 25 257 
, 128 * 8 
Key Ed Demo StatText Disabled 
76 14 306 504 5 360 25 393 
Invisible боАмау 
4 ;definition ID , 129 
0 ;ref con 1 
128 ;DITL ID ж 1 
StatText Enabled 
Type ALRT 5 3 48 305 
Key Ed Demo\@DCopyright Fabien Samuel and Mac Tutor 1988 
, 129 
42 102 94 410 , 130 
129 ;DITL ID 3 
CCCC ; Alert stages ж 1 
BtnItem Enabled 
, 130 15 6 95 66 
42 136 142 376 OK 
130 
5555 ж 2 
BtnItem Enabled 
Type DITL 75 170 95 230 
Cancel | 
128 = 
8 * 3 Pedi 
* | StatText Disabled == 
StatText Disabled 6 5 65 232 
5 3 25 89 Are you sure you want to load this mapping into the System 
Ascii Code : File and into RAM ? 
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Basic School 


Color & DragGrayRgn Explored 


MAC Il takes on BASIC 


Yes, [know thatit has been abouta year since the Macintosh 
П was released and not a word from me on how the Basic works 
on the Mac II. Тһе Mac П really is a wonderful machine, 
although there are still a few incompatibilities and inconven- 
iences. But all in all I still give the Mac II an A+. 

The curiosity lies in figuring out what works (or doesn't 
work) on the Mac II. The Mac II has features that did not even 
exist when most of the versions of Basic were written. Some 
things like color and screen size aren’t supported properly, or at 
all,even though the software was capable before the Mac П came. 

It’s fast. For example, just take a look at what it did for the 
Byte Magazine January 1983 Prime number benchmark pro- 
gram, known as the Sieve. ZBasic™ comes up with a 2 second 
time, MS Basic Binary interpreter with 129 second time (about 
the same as True Basic on the Mac Plus), and 15 seconds for the 
MS Basic compiler. Of course, everything is faster so it is all 
relative. Since we already know that the Mac II is faster and һауе 
a good idea about which versions of Basic are faster, there is no 
need to go into that here. For more information comparing the 
various versions of Basic, see MacTutor, Aug 1986, Feb. 1987 
and Mar. 1987. 


Screen Size: With the advent of the larger screen (also 
available for Mac Plus and SE) we see the need to be fully 
compatible with all size monitors. MS Basic opens its default 
windows to 512 X 342, the size of the SE and MacPlus screens. 
That works out alright since it still isn't known what kind of Mac 
might be running the program. Double-clicking the title bar 
causes MS Basic windows to zoom to full screen size. The LIST 
windows won't expand horizontally beyond the 512 limit, but 
will expand vertically to the bottom of the screen. The most 
annoying thing is that none of the windows can be moved below 
acertain point on the screen which is very close to the place where 
the bottom of the 9" screen would be (342). This means that you 
can never move the command window out of the way; you have 
to close it just like on a Mac Plus. 

True Basic v. 1.1, which I haven’ t looked at for awhile, opens 
the default window to full screen size. Of course, True Basic still 
has all the HFS problems and other limitations which I have 
discussed in past issues of MacTutor (Best of MacTutor Vol 2, pg 
379 or August 1986). (Version 1.1 is the latest that I have). 

ZBasic Ver. 4.1 windows also open to full screen size. There 
doesn't appear to be any compatibility problems here at all. As 
I write this, the ZBasic promised editor has still not been 
completed. 
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¿Basic 


Color support: This is only a big deal to those of you with 
а Mac II with a color monitor ( I wouldn't һауе one any other 
way!!). As you know, the original Quickdraw supports 8 colors 
already. I feel that it shows short-sightedness to not at least 
support that much. But both MS Basic and True Basic have NO 
color support even though both languages include means to 
change color from black to white. Other versions (on other 
computers whose names we won't say) of True Basic support a 
small set of colors. MS Basic uses color as a parameter in the 
syntax for the CIRCLE statement, yet you can't get any colors 
except black and white. 

ZBasic, however, does support the 8 colors in Quickdraw. 
That's only 8 colors for now, but I would expect that they will 
make improvements to this in some later version (who knows 
when?). So meanwhile, if you want color you will have to settle 
with the 8 basic colors. There are a few differences between 
ZBasic color statements and Quickdraw color statements. In 
order to standardize ZBasic, Zedcor has numbered the colors 
from 0 to 7. Quickdraw, however, has its own designation for 
each color as the following chart shows: 


COLOR TABLE 


COLOR ZBasic QuickDraw 
White 0 25 
Yellow 1 130 
Green 2 190 
Cyan 3 273 
Вше 4 305 
Magenta 3 137 
Red 6 205 
Black 7 10 


The color codes іп ZBasic and QuickDraw CANNOT be 
substituted for each other. You will have to either use Quickdraw 
graphics or ZBasic graphics or be careful not to mix the code with 
the wrong call. Sure, setting the color is easy, but be sure to use 
the right code with the right statement. 

This month's program demonstrates the colors available in 
ZBasic and gives you an example of its use. All you have to do 
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is set the color before issuing a graphics drawing statement and 
either Quickdraw or ZBasic (which probably uses Quickdraw 
anyway) will use the color you selected. 

What's missing? Color QuickDraw™ that's what. Fortu- 
nately, Zedcor has been very responsive to updating ZBasic. I'm 
sure that it isn'teasy for them to keep updating everyone so often. 
Let's hope that the next version of ZBasic will include the long 
awaited editor, Color QuickDraw and other major improve- 
ments. Read on! 


[The slowresponseby the Basic compiler makers to upgrade 

their products to meet the requirements of Mutifinder, System 4.2 
and the Macintosh II, has been really disappointing! There is still 
a pressing need for a reliable, engineering oriented Basic that 
. provides full access to the Macintosh capabilities and can func- 
tion in a workstation environment (ie, it can do math correctly 
and quickly). We encourage both the present Basic compiler 
makers to address this issue, as well as those we haven't seen in 
this marketplace, like Borland, to enter it, and hopefully unite a 
fragmented and frustrated market. -Ed] 


'ColorBasic 
'MacTutor, 1988 
'By Dave Kelly 


WINDOW OFF 

COORDINATE WINDOW 

"А color chart for future reference 
DIM rect%(3) 

MENU 1,0,1,”File” 

MENU 1,1,1,"Quit" 

EDIT MENU 2 

MENU 3,0,1,"Colors" 

MENU 3,1,1,"ZBasic'^ Commands" 
MENU 3,2,1,"ToolBox Commands" 
MENU 3,3,1,"Erase window" 
theEnd=0:REM theEnd will never come. 


'Make QuickDraw Color Assignments 
blackColor&z33 

whiteColor&=30 

redColor&=205 

greenColor&=341 

blueColor&=409 

cyanColor&=273 
magentaColor&=137 
yellowColor&=69 


‘Make ZBasic Color Assignments 
white=0 

yellow=1 

green=2 

cyan=3 

blue=4 

magenta=5 
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red=6 
black=7 


WINDOW 1,"Color Demo Window”,(4,38)-(450,200),4 
GOSUB “ZBasic™ Colors”: ' Print something to start 


ON MENU GOSUB "MenuEvent" 
MENU ON 
theEnd=0:REM theEnd will never come. 
DO 

UNTIL theEnd 


MENU OFF 


"MenuEvent" 
Menunumber%=MENU(0) 
Menuitem%=MENU(1) 
MENU 


IF Menunumber%=1 AND Menuitem%=1 THEN “Quit” 


IF Menunumber%=3 AND Menuitem%=1 THEN 
GOSUB “ZBasic™ Colors” 

IF Menunumber%=3 AND Menuitem%=2 THEN 
GOSUB “QuickDraw™ Colors” 

IF Menunumber%=3 AND Menuitem%=3 THEN 


CLS:PRINT@(1,3)’The Colors are now cleared!” 


RETURN 


"Quit" 
END 


“ZBasicTM Colors" 

CLS 

TEXT 2,14,0,0 
PRINT%(170,20) “ZBasic™ Colors" 
COLOR=white 

BOX FILL 5,50 TO 55,100 
COLOR-yellow 

BOX FILL 60,50 TO 110,100 
COLOR»-green 

BOX FILL 115,50 TO 165,100 
СОГ ОН=суап 

BOX FILL 170,50 ТО 220,100 
COLOR=blue 

BOX FILL 225,50 TO 275,100 
COLOR=magenta 

BOX FILL 280,50 TO 330,100 
COLORxred 

BOX FILL 335,50 TO 385,100 
COLOR:xblack 

BOX FILL 390,50 TO 440,100 
BOX 5,50 TO 55,100 

BOX 60,50 TO 110,100 

BOX 115,50 TO 165,100 

BOX 170,50 TO 220,100 

BOX 225,50 TO 275,100 

BOX 280,50 TO 330,100 

BOX 335,50 TO 385,100 


409 


ВОХ 390,50 ТО 440,100 

ТЕХТ 2,10 

PRINT%(25,48) white 
PRINT%(75,48) yellow 
PRINT%(130,48) green 
PRINT%(190,48) cyan 
PRINT%(240,48) blue 
PRINT%(300,48) magenta 
PRINT%(355,48) red 
PRINT%(410,48) black 
PRINT%(25,1 12) whiteColor& 
PRINT%(75,112) yellowColor& 
PRINT%(130,112) greenColor& 
PRINT%(190,112) cyanColor& 
PRINT%(240,112) blueColor& 
PRINT%(300,112) magentaColor& 
PRINT%(350,1 12) redColor& 
PRINT%(410,112) blackColor& 
TEXT 2,14 

PRINT%(150,140) “QuickDraw™ Colors” 
RETURN 


“QuickDraw™ Colors" 

CLS 

CALL MOVETO (170,20) 

CALL TEXTFONT(2) 

CALL TEXTSIZE(14) 

CALL DRAWSTRING (“ZBasic™ Colors") 
CALL SETRECT(rect%(0),5,50,55, 100) 
CALL FORECOLOR(whiteColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),60,50,110,100) 
CALL FORECOLOR(yellowColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),115,50,165,100) 
CALL FORECOLOR(greenColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),170,50,220, 100) 
CALL FORECOLOR(cyanColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),225,50,275,100) 
CALL FORECOLOR(blueColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect96(0),280,50,330,100) 
CALL FORECOLOR(magentaColor&) 
CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),335,50,385, 100) 
CALL FORECOLOR(redColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),390,50,440, 100) 
CALL FORECOLOR(blackColor&) 

CALL PAINTRECT(rect%(0)) 

CALL SETRECT(rect%(0),5,50,55,100) 
CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0),60,50,110,100) 


410 


CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0), 115,50, 165, 100) 
CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0), 170,50,220, 100) 
CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0),225,50,275, 100) 
CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0),280,50,330, 100) 
CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0),335,50,385, 100) 
CALL FRAMERECT(rect%(0)) 

CALL SETRECT(rect%(0),390,50,440, 100) 
CALL FRAMERECT(rect%(0)) 

CALL TEXTSIZE (10) 

CALL MOVETO (25,48) 

PRINT white 

CALL MOVETO (75,48) 

PRINT yellow 

CALL MOVETO (130,48) 

PRINT green 

CALL MOVETO (190,48) 

PRINT cyan 

CALL MOVETO (240,48) 

PRINT blue 

CALL MOVETO (300,48) 

PRINT magenta 

CALL MOVETO (355,48) 

PRINT red 

CALL MOVETO (410,48) 

PRINT black 

CALL MOVETO (25,112) 

PRINT whiteColor& 

CALL MOVETO (75,112) 

PRINT yellowColor& 

CALL MOVETO (130,112) 

PRINT greenColor& 

CALL MOVETO (190,112) 

PRINT cyanColor& 

CALL MOVETO (240,112) 

PRINT blueColor& 

CALL MOVETO (300,112) 

PRINT magentaColor& 

CALL MOVETO (350,112) 

PRINT redColor& 

CALL MOVETO (410,112) 

PRINT blackColor& 

CALL TEXTSIZE(14) 

CALL MOVETO (150,140) 


CALL DRAWSTRING (“QuickDraw™ Colors”) 


RETURN 


Basic Answers to Basic Questions 


Concerning the comment in the Nov. 1987 issue of MacTu- 
tor where Steve Millman suggested a method of applying an 
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eventloop for reading disk events: The main problem here is that 
a disk event might be inserted while not in the GetNextEvent 
loop. The disk insert would be missed completely. I have been 
assured by Zedcor that in a future release of ZBasic they will add 
the Disk insert event to the DIALOG functions. This is easy for 
them to do since GETNEXTEVENT returns this to them any- 
way. For now, just do what Steve Millman suggests or don't 
bother checking for disks at all until the new improvements 
come. 

Q. Iwanttouseinmy program aDragGrayRect statement 
(the same as you see in MS Basic), but I want to use it in ZBasic. 
Is this possible? 

A. DragGrayRectisonly available as an MS Basic library 
call (previously known as a Clear Lake Research Library call). 
The alternative is to use DragGrayRgn where the region is in the 
shape of a rectangle. DragGrayRgn is a ROM call where as 
DragGrayRect is a library subroutine derived from ROM calls 
(probably uses DragGrayRgn). Another alternative that would 
require more work would be to write your own DragGrayRect 
function to use in any of your programs. The following program 
includes an example of this function. The function itself can be 
saved to the disk with ЗАУЕ+ and retrieved later for use in other 
programs with APPEND. Hope that this helps. 


‘Drag Example 
Ву Dave Kelly 
‘©MacTutor, 1988 


WINDOW OFF 

COORDINATE WINDOW 

DEF MOUSE--1 

DIM Rect%(3),pt%(1),pin%(3),bnd%(3),dir%,dis& 
pt%(0)=mousey%:pt%(1)=mousex% 

‘Create DragGrayRect function 

LONG FN DragGrayRect&(RL%,RT%,RR%,RB%, 
mousey,mousex, PL%,PT%,PR%,PB%,BL%,BT%,BR%, 


BB%,dir%) 

‘ Rect% = the rectangle to be moved 

' p% = {һе point where the mouse was pushed. 

‘ pin% = the rectangular limits in which outline can be 
| | dragged. 

' bnd% = the rectangular boundary for а drag. 

°  dir?e» the direction to which the drag is constrained 

i 0 = no constraint, 1 = horizontal, 2 = vertical 
'  dis&s A point array that returns drag displacement. 


CALL SETRECT(Rect%(0),RL,RT,RR,RB) 

CALL SETRECT(pin%(0),PL,PT,PR,PB) 

CALL SETRECT(bnd%(0),BL,BT,BR,BB) 

RgnHand&=FN NEWRGN 

CALL OPENRGN 

CALL FRAMERECT(Rect%(0)) 

CALL CLOSERGN(RgnHand&) 

pt%(0)=mousey%:pt%(1)=mousex%:Proc&=0:dis&=0 

dis&=FN DRAGGRAYRGN(RgnHand8, pt%(0), 
pin%(0), bnd%(0), dir%,Proc&) 
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CALL DISPOSERGN(RgnHand&) 
END FNzdis& 
'Find out monitor size 
CALL GETWMGRPORT(WMgrPort&) 
РойТор=РЕЕК WORD(WMgrPort&48) 
Рог ей=РЕЕК WORD(WMgrPort&-10) 
PortBottom=PEEK WORD(WMgrPort&+12) 
PortRightsPEEK WORD(WMgrPort&- 14) 
WINDOW! ,"DragExample", (PortLeft.-4, Port Top+42)- 

(PortRight-6, PortBottom-6),5 

MENU 1,0,1,”File” 
MENU 1,1,1,"Quit" 
top=100:left=100 
GOSUB "DrawBox" 
MOUSE ON:MENU ON:DIALOG ON 
ON MOUSE GOSUB "MouseEvent" 
ON MENU GOSUB "MenuEvent" 
ON DIALOG GOSUB "DialogEvent" 
"Loop" 
DO 
UNTIL Done 
MOUSE OFF:MENU OFF:DIALOG OFF 


"DialogEvent" 
D=DIALOG(0) 

IF D=4 THEN END 
RETURN 


"MenuEvent" 

Menunumber=MENU(0) 

Menuitem=MENU(1) 

IF Menunumber=1 AND Menuitem=1 THEN END 
MENU 

RETURN 


“MouseEvent” 

X=MOUSE(0) 

mousey=MOUSE(2):mousex=MOUSE(1) 

dir%=0 

dis&= FN DragGrayRect&(left,top, left+100, top+100, mousey, 
mousex, PortLeft, PortTop, PortRight, PortBottom, 
PortLeft, PortTop, PortRight,PortBottom,dir%) 

dy=FN HIWORD(dis&) 

dx=FN LOWORD(dis&) 

LONG IF dx<>0 AND dy<>0 
CALL ERASERECT(Rect%(0)) 
top=top+dy:left=left+dx 
GOSUB "DrawBox" 

END IF 

RETURN 


"DrawBox" 

CALL SETRECT(Rect%(0),left,top,left+100,top+100) 

CALL FORECOLOR(205): ' color = red ӨЛ 
CALL PAINTRECT(Rect%(0)) so} 
RETURN 


Basic School 
Updating Windows in Basic 


Dave Kelly is an electrical engineer for General Dynamics 
in Pomona, where he is involved in using work stations for 
hardware design. He is a founding editorial board member and 
currently an active board member for MacTutor. 


A fresh window lets you see things more clearly. (I like mine 
in color, but black & white mode on the Macintosh II sure is 
faster). Ireceived the following request from one of our readers 
which I'm sure others of you would also like to know about: 


Q. Iam working on an application in ZBasic 4.00 that I hope 
to release commercially. Previously I never had to worry about 


handling update events in a “correct” manner (in the past I have 
always reprinted everything on the screen when I’ve encountered 
an update event). ZBasic does provide a WINDOW PICTURE 
statement that I have not gotten to work to my satisfaction. I have 
also tried GET and PUT without much success. I’m obviously 
doing something wrong. ...could you show various ways to 
handle update events that involve DAs and multiple windows? 
My application has Edit Fields and displayed text (i.e. displaying 
results obtained from values entered in the edit fields). 


A. Yes, there can be some ticky problems associated with 
refreshing windows which use edit fields. There is a standard 


way that refreshing should work. In Pascal the application should 
respond by calling BeginUpdate, drawing the window, then call 
EndUpdate. The Window Manager section of Inside Macintosh 
explains how to do this. That’s fine when using the Macintosh 
standard GetNextEvent loop, but in ZBasic the approach must be 
modified. 

The object is to restore any window which gets covered up 
by another window. If window 1 is dragged over window 2, then 
if window 2 is selected it should automatically be redrawn. Or 
if only part of window 2 is covered up and window 1 is removed 
then window 2 should be refreshed. This means that you as a 
programmer are responsible to determine all of the possible ways 
the window could be erased and be sure to set up event handling 
to cover all the possibilities. 

There are 3 options we have for screen refresh with ZBasic. 


1. Redraw the picture in response to a DIALOG event. 
2. Use the WINDOW PICTURE statement. 
3. Use GET and PUT in response to a DIALOG event. 


By the end of this discussion you will know when to use each 


method in different circumstances. Directly redrawing the 
window is probably used most often by those that don't know 
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€ File Edit Window 


MacTutore 


The Best in the West! 
This is the first window 


The edit field Read MacTutor! 


Read lIscTutor! 


Fig. 1 Our Multiple Window Example 


about the other two methods (or don't know how they work). 
Redrawing is what I think of as the “brute force" method. It is 
usually the method used for “quick and dirty" screen refresh. The 
advantage is that you have control to force the update to occur 
whenever you feel like it. The disadvantage is that itis slower and 
you may find that the screen may get updated sometimes when 
it doesn't need it (in order to catch every possible event). 

To refresh by redrawing in the "brute force" mode a DIA- 
LOG(0)=5 event should effectively determine when a window 
needs to be refreshed. The window that needs to be refreshed is 
returned in the DIALOG(5) function. A quick call to the screen 
drawing routine when DIALOG event occurs is all that is needed 
to make this work. 

The 2nd method of refreshing the screen is somewhat unique 
to ZBasic. Using the WINDOW PICTURE statement is the most 
automatic way to update the screen. А good example of using 
WINDOW PICTURE is given in the ZBasic manual on page E- 
158. The example at the end of this column also demonstrates its 
use. There are a few problems which you should be aware of. 
When using WINDOW PICTURE, all DIALOG events for the 
window involved are not passed to the DIALOG function, but 
instead are automatically handled by the WINDOW PICTURE 
statement. This is both good and bad. Itis good because now any 
portion of the screen can be refreshed automatically without 
really trying. The problem comes when you use an EDIT FIELD 
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inthe window which you аге using WINDOW PICTURE. When 
WINDOW PICTURE is active, the EDIT FIELD is not updated 
properly. Ordinarily the EDIT FIELD is automatically updated, 
but not with WINDOW PICTURE. This is one of those cases 
where the window should be refreshed with the “brute force” 
method. The process can be improved by setting up the screen 
information to be updated in a PICTURE so thatitcan be redrawn 
quickly. The demo shows how this is done. The *Set Window 
1 Update" routine is called whenever an update event occurs. 
Also the EDIT FIELD value is re-read and the text displayed is 
obtained from the current contents of the EDIT FIELD. It is 
really too bad that in ZBasic the WINDOW PICTURE statement 
doesn’t update controls. [My guess is that WINDOW PICTURE 
is nothing more than the automatic window updating procedure 
of placing a quickdraw picture handle in the window record' s pic 
field, in which case, no controls or edit fields would be updated. 
This method was only intended for fairly static window contents, 
and never meant to be a true update procedure for dynamic 
windows. -Ed] 

To use WINDOW PICTURE you first define the PICTURE 
which you want to print. This can be a combination of text and 
graphics. The PICTURE is pointed to by a variable which is used 
in the WINDOW PICTURE statement to initialize the automatic 
update routine. To stop the update or to modify it you can use 
WINDOW PICTURE #1,0 (if using window #1) and then KILL 
PICTURE to delete the picture from memory. If you don’t 
remove the pictures from memory, they may use up some of your 
memory and sooner or later if enough pictures are used, you 
could run out of memory. 

I think the 3rd method is a bit more cumbersome than the first 
two. I call it the “GET/PUT” method. First, the window contents 
are drawn for the first time. Then the rectangle containing the 
contents of the window must be determined exactly. These 
coordinates are plugged in to an equation given on page 232 of 
the ZBasic manual. The equation determines the number of bytes 
to use in a DIM statement for the graphic image used in the GET 
and PUT statement. The equation is: 


bytes = 6 + ((2-yD* D * CG2-xD*1) * bpp + 7) / 8 


where x1, уі are the coordinates of the upper-left-corner of 
the graphic image on the screen; x2, y2 are the coordinates of the 
lower-right-corner of the image. The bits-per-pixel, bpp, de- 
pends on your Macintosh screen setup. Standard black & white 
Macintoshes have one bit per pixel, a Macintosh II with sixteen 
colors is 4 bpp and 256 colors is 8 bpp. Now divide the number 
of bytes by two for the integer (16 bit) array used in the DIM 
statement. This is the extent of the difficulty in using the *GET/ 
PUT" method. The DIM statement should be executed only once 
at the beginning of your program and enough space should be 
allocated for whatever you plan to update. After the screen is 
drawn the first time, the GET statement is used to set the array to 
the screen image. If your array isn’t dimensioned big enough you 
can definitely expect a system bomb here. I would recommend 
that you only use the *GET/PUT" method when уоп are not going 
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to change the window contents. The PUT statement is called by 
the DIALOG event routine whenever the window needs refresh- 
ing. (Mac II color users, notice that the PUT statement only 
refreshes in black & white; the color information is ignored. This 
is unfortunate. Maybe in a future release of ZBasic with 256 
color support?????). 

The demo program demonstrates the three methods dis- 
cussed above. Try opening DAs and dragging a window on top 
of other windows and closing/opening them. I feel that this 
program should give you a good idea of how windows can be 
refreshed. I strongly recommend that most of your refreshing be 
done with the WINDOW PICTURE statement whenever pos- 
sible. (NOTE: *whenever possible” is just about always, except 
when controls are used on the same screen. Maybe this will get 
fixed someday too so that WINDOW PICTURE will work when 
EDIT FIELDS are active). 

This has been a much more pleasant program to write as 
Zedcor has released version 4.01 with a much improved editor. 
The editor isn't perfect, but if you remember to save your 
program often enough you can get by without exiting ZBasic. 
Also, they have added DIALOG(0)=17 for disk inserts. DIA- 
LOG(17) returns the disk drive which the disk was inserted. 
ZBasic is still the best Basic available today and keeps looking 
better each new release. Zedcor, keep up the good work. 

Zedcor and True Basic have announced new versions at the 
San Francisco Expo. Watch for details on these new products. - 
Ed 


* WINDOW UPDATE DEMO 
* ©1988 MacTutor® 
’ By Deve Kelly 


WINDOW OFF 
COORDINATE WINDOW 
DEF MOUSE-- 1 

DIM Wptr&C3) 


APPLE MENU “About Updating...” 
MENU 1,0, 1, "File" 

MENU 1, 1, 1, "Quit" 

EDIT MENU 2 

MENU 3,0, 1, "Window" 

MENU 3, 1, 1, "Show Window 1" 
MENU 3,2, 1, "Show Window 2" 
MENU 3,3, 1, "Show Window 3" 
MENU 3,4, 1, "Show А11 Windows” 


"Find out monitor size just in case we need it 
CALL GETWMGRPORTCWMgrPor t&) 

PortTop-PEEK WORDCWMgrPor t&+8) 

PortLef t-PEEK WORDCWMorPort&+ 10) 
PortBottom-PEEK WORDCWMorPor t&+ 12) 
PortRight=PEEK WORDCWMgrPor t&+ 14) 


WINDOW! 1, “Window 1", CPortLeft*4,PortTop*42)-C300,300),5 
Wptr&C1)-WINDOWC14) 

TEXT 3,12 

EDIT FIELD 1, "Read MacTutor!^,(50,200)-(270,225), 1 
GOSUB “Set Window 1 Update" 


WINDOW82, "Window 2", (PortLeft+24,PortTop+62)-(328,320),5 
Wp tr&(2=WINDOWC 14) 

‘NOW... Create the picture for the first window 

PICTURE ON 

TEXT 2,24, 1 
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COLOR=4 

PRINT@C3, 12^MacTutor e^ 

COLOR=7 

TEXT 3, 12,0 

PRINT6C6,42^The Best in the West!" 
PRINTe(5,6)^This is the second window” 
PICTURE ОҒҒ,Ріс2% 

PICTURE, Ріс2%:” Draw the picture 
WINDOW PICTURE *2,Pic2& 


WINDOW#3, “Window 3",CPortLef t+44, Por tTop+82)-(348,348),5 
Wptr&C3)-WINDOWC 14) 

х1=0:х2=300:у1=0:42=300 

' bytes used = 6 + ((y2-yD* D * CO2-x1* D* bpp + 7) / 8) 
DIM Pic3$(58293) :” space for 32 bits-per-pixel (МАС II) 
‘ NOW... Create the picture for the third window 

TEXT 2,24,1 

COLOR=4 

PRINT@C3, 1)*MacTutore” 

COLOR=7 

TEXT 3, 12,0 

PRINT@(6,4)*The Best in the West!” 

PRINTe(5,6)"This is the third window" 

GET (x1,y1)-Cx2, y2),Pic3%C1) 

PUT (8,0),Pic3%¢1),0 


ON DIALOG GOSUB "DialogEvent"^ 
ON MENU GOSUB “MenuEvent’” 
FLUSHEVENTS 

MENU ON:DIALOG ON 


“Loop” 
GOTO “Loop” 
MENU OFF:DIALOG OFF 


*DialogEvent^ 
D-DIALOGC?) 
ern 


ASE 3 
WINDOW DIALOG(3) 
ASE 


4 
CALL HIDEWINDOWCWptr&CDIALOGCA22) 
CASE 5,6,7 
IF DIALOG(5)=3 THEN GOSUB^W indow3 Update” ELSE 
GOSUB “Set Window 1 Update” 
END SELECT 
RETURN 


“MenuEvent” 
Menunumber=MENUCO) 
Menu i tem=MENUC 1) 
MENU 
SELECT Menunumber 
CASE 255 
GOSUB “AppleMenu” 
CASE 1 


GOSUB "FileMenu^ 
CASE 3 
GOSUB "WindowMenu"^ 
END SELECT 
RETURN 


*AppleMenu^ 

WINDOW 4,7” С 100, 1002- (400,250), -2 
PICTURE ON 

TEXT 0,12,0,0 

PRINT 6(2,2) “CZBASIC) Window Update Demo V1.0” 
PRINT 8C10,32^by^ 

PRINT 8C8,42"Dave Kelly” 

COLOR=6 

PRINT @(7,6)%@MacTutor, 1988" 
COLOR=7 

PRINT 6(7,72"7Besic version 4.01" 
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PICTURE ОҒҒ,Ріс4% 
PICTURE ,Ріс4% 

WINDOW PICTURE *4,Pic4& 
MOUSE ON 


DO 

mous-MOUSE(?2 > 

outsiderect=(MOUSEC 1«0 OR MOUSEC 12:300 OR MOUSE(2)«0 OR 
MOUSE(2)> 150) 

IF MOQUSEC 12-0 AND MOQUSE(2)=8 THEN “Stop” 

UNTIL mouso2 AND NOT Coutsiderect) 

MOUSE OFF 

KILL PICTURE Pic4&:’ Delete the picture from memory 
DIALOG ON 

WINDOW CLOSE 4 

DIALOG OFF 

RETURN 


“Window3 Update” 
ActiveWindow-W INDOWC2) 
WINDOW OUTPUT 3 

PUT (0,02,Ріс3%(12,0 
WINDOW OUTPUT ActiveWindow 
RETURN 


“Set Window 1 Update” 

ActiveWindow-W INDOWCO) 

WINDOW OUTPUT 1 

'NOW... Create the picture for the first window 
КІШ PICTURE Рісі% 
PICTURE ON 
TEXT 2,24,1 
COLOR-4 
PRINT@C3, 12^MacTutore^ 
COLOR=7 
TEXT 3,12,0,0 
PRINT@(6,4)*The Best in the West!” 
PRINT@(5,6)*This is the first window" 
Editvar iable$=ED ІТ 1) 
PRINT6(5,8)^The edit field = “;Editvariable$ 
PICTURE OFF,Pici& 

PRINT@C5,8);SPCC 100) 

PICTURE, Pici&:’ Draw the picture 

WINDOW OUTPUT ActiveWindow 

RETURN 


*FileMenu^ 
IF Menuitem=1 THEN “Stop” 
RETURN 


*^WindowMenu^ 
SELECT Menuitem 
CASE 1 
CALL SHOWWINDOW(Wptr&C120:WINDOM 1 
2 


CALL SHOWWINDOWCWptr&(2)): WINDOW 2 
3 
CALL SHOWWINDOWCWptr&(3)): WINDOW 3 
4 
FOR i=1 T03 
CALL SHOWWINDOW(Wptr&Ci 2) 


WINDOW i 
NEXT i 


CASE 


END SELECT 
RETURN 


“Stop” 

WINDOW PICTURE *1,8:’Don’t update the first window anymore 
KILL PICTURE Pici&:’ Delete the picture from memory 

WINDOW PICTURE #2,0:’Don’t update the second window anymore 
KILL PICTURE Pic2&:’ Delete the picture from memory 

END = 


Sel 


cau 
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basic School 


Color Mixer Creates Custom Colors 


ZBasic Does Mac Il Color! 


Yes,that'sright! The new ZBasic version 4.01 now supports 
the Mac II's full 256 colors. There is no need to restrict yourself 
to the 8 colors of the old Quickdraw. 

To use the 256 color mode, ZBasic now provides a LONG 
COLOR statement. Тһе syntax is: LONG COLOR blue%, 
green%, red%, [ background]. LONG COLOR is used to set the 
colors and grey levels for subsequent graphic commands used on 
the Macintosh II. The command is ignored by other Macs. 

The values of blue%, green% and red% may range from 0 to 
65535. They may also be represented as long integers (65535 as 
a long integer is -32767 as a regular integer). The colors аге used 
in RGBColor calls to the Mac ПЕОМ where O is the darkest and 
65535 is the lightest. 

The background variable is used as a flag to indicate if the 
color should be set in the foreground or in the background. A 
background value of 0 causes the background color to be set to 
the blue%, green%, red% color indicated. Subsequent LONG 
COLOR statements that have no background variable or back- 
ground is set to other than 0 will set the foreground color. The 
background color will be used the next time itis needed, when the 
screen gets updated or is cleared with CLS. 

Inside Macintosh Volume V has the new color information 
we need to understand how the Mac II gets its color and how to 
use color in your applications. Before using color you should 
read the User Interface chapter of Inside Macintosh Vol. V. One 
of the most important thing you should try do is leave the 
selection and choices of color in the hands of the user. The study 
of color and how it affects people is not well defined. One of my 
co-workers is color-blind and has a totally different way of 
looking at color than I do. If color is not used carefully it could 
hinder instead of help to enhance your software. 

Traditionally (and on that other computer) color has been 
used to help distinguish different things on the screen and show 
relationships between items on the screen. Some colors have 
special significance. For example: red means stop, green means 
go, yellow means caution. Colors can enhance in this way, 
however, remember that after the user has seen the same color 
combinations several dozen times, the color becomes common- 
place and he might still make mistakes that the color was 
supposed to help him avoid. In fact, the brightcolors used to warn 
a user may actually attract him to select that color. 

Inside Mac encourages you to start out the design of your 
program in black and white and add color as a supplement to 
provide extra for people who have color capability. Color use 
should be limited to the content area of your windows. Let the 
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| | Blue: 65533 Red: 65533 Green: 65533 


Fig. 1 Mixing colors, in this case white! 


user decide what color his menus, borders, controls etc. should 
be. The Colorizer application and CDEV let the user select his 
own colors for these items. If the user selects colors for some- 
things then your application comes along and changes part of 
these colors, there might be some pretty strange color combina- 
tions left over. Many suggestions are available in Inside Mac 
which you should know so that your applications will be consis- 
tent and won’t conflict with the user interface. 

The blue%, green%, and red% that you specify in the LONG 
COLOR is used by the Color Manager to return the pixel value 
that best represents that color. The Color Manager searches 
through the color table for the RGB color that most closely 
matched the desired color. Color Quickdraw then places that 
color on the screen. The way that each pixel is assigned a color 
to display is by way of the Color Look-Up Table (CLUT). The. 
video card takes each pixel and compares it to the CLUT to 
determine which RGB value that pixel represents. The RGB 
value is split off into three separate electrical signals (red, green, 
and blue) to the video monitor. By the way, when 
red=green=blue you get shades of gray. By using the Palette 
Manager (if you could from Basic) you could change the drawing 
environment to use a different palette. 
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Color Selection 


Color Selection routines have been provided to the Macin- 
tosh II by Apple via the Color Picker routines. Here is the 
problem: ZBasic doesn't support all the new calls for the Mac II 
yet. Zedcor has promised to send me format and structure 
information to add more calls to ZBasic as required, but Andy 
Gariepy has been to busy to send it to me. So... that being the case 
I have no choice but to write my own color selection routines. 
Also the Color Picker is PACK 12 in system 4.2. I'm not sure 
it would be that easy to call a PACKage from ZBasic without it 
being defined by the language itself. Maybe we will have to wait 
forZedcor toimplement it. Inthe mean timeI have made my own 
"quick and dirty" version of a “Color Picker". 

If you think about it, the Apple Color Picker routine really 
does do alot! It allows you to type in the red, green, blue colors, 
but also will adjust these colors when you set the hue, saturation, 
and brightness. Proper adjustment of the red, green, and blue will 
result in the same hues, saturation, and brightness, but it just isn't 
as convenient to setup. 

The color wheel concept is interesting too. You can learn a 
lot about how colors can be mixed by watching the values of red, 
green, and blue while moving the mouse around the color wheel. 
Move more towards blue and watch how the numbers change! 
Amazing! The color wheel really is a good way to allow you to 
select colors. The only other good approach is to allow the user 
to pick from a color palette. The problem is how to decide which 
colors are defined in the palette. 


My example suggests a simple way that colors could be 
selected by the user. By choosing the Pick Colors menu or button 
you are given a set of 3 scroll bars to adjust the amount of blue, 
green, and red. You can mix the amount of each color and see the 
effect of mixing each. This might even be useful for showing 
young children the effects of mixing colors. If you like the color 
then click on OK or else cancel to return to the original color 
setting. 


The problem with my Color Selection demo is that because 
of the way ZBasic does event trapping it is difficult to make the 
routines be stand alone. My color mixer program provided here 
must become an integral part of the application because of the 
way that ZBasic “automatically” generates the event loop. I tried 
using separate ON DIALOG GOSUB traps, but it somehow 
didn't work. I could only get one of the ON DIALOG statements 
to take effect. 

There are a few problems that have shown up with my early 
version of ZBasic 4.01. First, the scroll bars don't scroll properly 
when using the max and min values that are given in the ZBasic 
manual. If +32767 is used and you scroll to the right (or down) 
by clicking on the right (or down) arrow, when the bar reaches the 
max it will jump to the minimum! Also if you change the max 
value to between 32100 and 32766 and click in the scroll bar 
between the arrow and box, when the max is reached it also jumps 
down to the minimum. UGH! And... if -32768 is used for the 
minimum the scroll bar returns aO when the box is set at the mini- 
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mum. -32767 works fine. I am forced to adjust these values in 
the program, but it won't matter much because the selected color 
will likely be the same anyway because we only have 256 
possible. 


Hierarchical Menu Notes 


Using Hierarchical menus isn't so simple with ZBasic. 
Hierarchical menus are stored as resources of the type MENU 
just as other menus may be stored. However, to use MENU 
resources with ZBasic AND have ZBasic be able to use them, you 
have to set up your own event loop using GETNEXTEVENT. 
Then you have to handle each event with the standard Macintosh 
way of programming and can't use ZBasic's event trapping 
routines (they get in the way). What we need is a way to use 
MENU, WINDOW, CONTROLs and other resources from 
ZBasic which can be invoked with ZBasic statements (which are 
integrated in with the ZBasic "automatic" event loop. It would 
also be useful to be able to automatically install a resource into 
an application when ZBasic compiles as an application. Maybe 
Zedcor can put these things on their “THINGS TO DO” list for 
version 4.02? 


А submenu is associated with a menu item by using 2 fields 
of the Menulnfo data structure. When the itemCmd field is set 
to hex $1B, the itemMark field should contain the menuID (in 
hex) of the associated hierarchical menu. These values can be 
created/modified with ResEdit 1.1B3. 


By using Menu Manager calls (pg. E-181 in ZBasic manual) 
you can find out which menu is selected in the GETNEXTE- 


VENT loop as you would with regular type menus. More on this 
in a future column. 


'Professor Мас”5 ZBasic Color Mixer 
‘MacTutor 1988 
'By Dave Kelly 


WINDOW OFF 
COORDINATE WINDOW 
DIM Colorbox$(3) 
red&=0 

blue&= 

green&=9 


DEF MOUSE--1 

false=0: true-NOTCfalse) 
MENU 1,20, 1, “File” 

MENU 1, 1, 1, Select Color” 
MENU 1,2, 1, “Quit” 

EDIT MENU 2 


'Find out screen size. 

CALL GETWMGRPORTCWMgrPor t& > 
PortTop-PEEK WORDCWMgrPor t&+8) 
PortLef t=PEEK WORDCWMgrPor t&+ 19) 
PortBottom=PEEK WORDCWMorPor t&+ 12) 
PortRight=PEEK WORDCWMgrPor t&+ 14) 


WINDOW 1, “Main Window’, (19, 44)-CPor tRight—4, Por tBottom-4) 
TEXT ,,,0 
BUTTON #6, 1, Quit’, C20, WINDOWC32-50)-(85, 

WINDOWC32-30), 1 


BUTTON #7, 1, "Pick Color”, (120, WINDOW(3)-50)-( 195, 
WINDOWC32-30), 1 
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CALL SETRECTCColorbox8C0), 10, 10, W INDOWC22- 10, 
WINDOWC32-215) 

PICTURE ON 

LONG COLOR blue&, greenk, red& 

CALL PAINTRECT(Colorbox%(@)) 

CALL MOVETOC20, WINDOWC32- 100) 

COLOR-7 

PRINT ^Blue:^;blue&;" Red: ";red&;" Green: *;green&; SPACE$C10) 

PICTURE ОЕР, Ріс1& 

PICTURE, Р1с1% 

WINDOW PICTURE #1,Pic1& 


ОМ DIALOG GOSUB "Event" 
ОМ MENU GOSUB "MenuEvent"^ 
DIALOG ON:MENU ON 

“Loop” 

GOTO “Loop” 

DIALOG STOP:MENU STOP 


“MenuEvent” 
Menunumber-MENUC?) 
Menu itemzMENUC 1) 
MENU 
IF Menunumber« 1 THEN RETURN 
SELECT Menuitem 

CASE 1 

GOSUB "ColorPick^ 
SE 2 


GOSUB “Quit” 
END SELECT 
RETURN 


“Quit” 

WINDOW PICTURE 81,0 
KILL PICTURE Pic1& 
END 


*ColorPick^:^A Color Selection routine 

done=f alse 

min%=-32767: ‘Manual says that -32768 is Min. 

max%=32766: ’Manual says that 32767 is Max. 

currentred&=red& 

currentblue&-blue& 

currentgreen&-green& 

WINDOW 5, "Color Chooser”, (PortLef t* 10, PortTop*30)- 
(PortRight-19, PortBottom- 10), -2 

SCROLL BUTTON * 1,currentbl1ue&-32767, піп тах, 100, (20, 
WINDOW(3)-200 -CWINDOW(2)-20, V INDOWC32-290* 165,0 

SCROLL BUTTON *2,currentgreen&-32767, ming, max%, 100, 
(20, WINDOWC32-150)-CW INDOWC22-20, WINDOWC32-150* 162,0 

SCROLL BUTTON 83,суггепігес%-32767, ming, max%, 100, (20, 
МІМООМСЗ )- 100)- CWINDOWC22-20, W INDOWC32- 100+ 162,0 

BUTTON #4, 1, “ОК”, C20, WINDOW(32-50)-(85, 
WINDOWC32-30), 1 

BUTTON #5, 1, “Cancel”, C120, WINDOW(3)-50)-( 185, 

WINDOWC32-30), 1 

TEXT 0,12,0,0 

CALL MOVE TOCWINDOW(2)/2, WINDOW(3)-200+30) 

String$="Blue: "*STR$Ccurrentblue&) 

COLOR=4 

CALL DRAWSTRING(String$) 

CALL MOVETOCWINDOWC22/2,W INDOWC32- 150+30) 

String$-"Green: “+STR$(currentgreenk) 

COLOR=2 

CALL DRAWSTRING(CString$) 

CALL MOVETOCWINDOW(2)/2, WINDOWC32- 100+30) 

String$=*Red: "*STR$Ccurrentred&) 

COLOR=6 

CALL DRAWSTRING(CStr ing$) 

GOSUB “UpdateColorBox” 

FLUSHEVENTS 

RETURN 


*ButtonEvent^ 
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Buttonnumber-DIALOGC 1) 
Buttonva lue&=BUT TONCBut tonnumber 2*32767 
SELECT Buttonnumber 
CASE 1 
GOSUB *Button1^: бей blue 
2 


GOSUB “Button2’: set green 
3 


CAS 
GOSUB “Button3’: et red 
CASE 4 
GOSUB "Button4^:^ OK button was pressed 
CASE 5 
GOSUB ^Button5^:^ Cancel button was pressed 
ASE 6 


650598 “Quit” 
CASE 7 

.. 60SUB "ColorPick^ 
END SELECT 
RETURN 


*UpdateColorBox^ 

LONG COLOR currentblue&,currentgreen&, currentred& 

CALL ЗЕТКЕСТССо1огбох%(0), 10, 10, WINDOW(22- 10, 
WINDOWC32-215) 

CALL PAINTRECTCColorbox$(22) 

RETURN 


“Button”: blue scroll bar 

currentb lue&=But tonvaluek 

CALL MOVETOCW INDOWC22/2, W INDOWC32-200*30) 
String$-"Blue: **STR$(currentblue& )*SPACESC 10) 
COLOR=4: set text color to blue 

CALL DRAWSTRINGCStr ing$) 

GOSUB "UpdateColorBox^ 

RETURN 


*Button2^:'green scroll bar 
currentgreen&-Buttonvalue& 

CALL MOVETOCWINDOW(2)/2, WINDOW(3)- 150430) 
String$=*Green: “+STR$Ccurrentgreenk)+SPACE$( 10) 
COLOR-2:'set text color to green 

CALL DRAWSTRINGCStr ing$) 

GOSUB “UpdateColorBox” 

RETURN 


*Button3^:^red scroll bar 
currentred&-Buttonvalue& 

CALL MOVETOCWINDOW(2)/2, W INDOWMC32- 100430) 
String$-"Red: *"*STR$Ccurrentred& )*SPACESC 10) 
COLOR-6:'set text color to red 

CALL DRAWSTRINGCStr ing$) 

600508 "UpdateColorBox^ 

RETURN 


*Button4^: ^0K button 
red&-currentred& 
blue&=currentb lue& 
green&=currentgreenk 
GOSUB “Closestuff” 
RETURN 


*Buttonb^: Cancel button 
GOSUB ^Closestuf f^ 
RETURN 


*Closestuf f ^ 

FOR J-1 705 
BUTTON CLOSE J 

NEXT J 

WINDOW CLOSE 5 

PICTURE ON 

LONG COLOR blue&,green&,red& 

CALL PAINTRECT(Colorbox%(@)) 

CALL MOVETO(C20, WINDOWC3)- 100) 
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COLOR-7 

PRINT ^Blue:^;blue&;^ Red: ^;red&;^ Green: ^;green&; ЗРАСЕ$ (18) 
PICTURE OFF,Picl& 

PICTURE, Pici& 

WINDOW PICTURE *1,Pici& 

RETURN 


“Event” 
D-DIALOGC?) 
SELECT D 
CASE 1 
GOSUB "ButtonEvent^ 
4 


GOSUB "Quit^:^if close box selected 
END SELECT 
RETURN 


Hypercard Tidbits 


At MacWorld Expo in San Francisco someone asked if we 
knew a way to effectively mask out the command-option keys in 
HyperCard. The following information was given in WINOID 
issue 41, a newsletter for the Apple HyperCard Users Group. I 
hope that this will answer your question. 

How can I hide buttons from command-option key peek? 

When you don't want people peeking at your buttons, it is 
necessary to trap the command and option keys. While there are 
several ways of doing this, here is one that is simple and works 
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about 99% of the time. 

The basic idea is to take the user to another card when the 
command and option keys are both pressed. This can be a “по 
peeking" card or a rules card or some other kind of card. When 
the user releases both keys, you then return to the card the user 
was viewing before trying to peek. Following are the two scripts 
that accomplish this. Put the top one in your stack script and the 
other in the "no peeking" card script. 


For the stack script: 


On Idle 
if the commandkey is down and the optionkey is down then 
push this cerd 
go card “no peeking” 
end if 
end Idle 


For the “no peeking” card script: 


On Idle 
if the commandkey is up and the optionkey is up then 
pop card 
end if 
End Idle 


Sell 


«ақа» 
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Basic School 
Quick & Dirty Data Conversion 


FILE IMPORT/EXPORT with BASIC 

Over the years, one of the most beneficial uses for Basic is 
the ability to quickly write programs to import/export data to and 
from data bases. This also provides a “quick and dirty" way to 
convert data or suppress unwanted characters. I'd like to explain/ 
complain about the process and some of the problems that I have 
encountered. 

My first major data conversion came a couple of years ago 
when I converted 30,000 names in a mail list from my Apple // 
e to the Macintosh. Yes, this was quite a feat, mostly because of 
the bottle neck which the dinky 143K floppy drives allowed on 
the Apple //. And you thought the Mac 400K drives were small! 
Anyway, on the Apple //e I was using DB MASTER, a now 
orphaned product, with some small support still available from a 
consulting firm in Northern California. There may be some of 
you that are familiar with DB MASTER (sometimes it was 
referred toas DB MONSTER). DB MASTER was great for mail 
lists and still would be today except for it's slow speed (that's 
partly the Apple //s fault). 

The process went something like this: First the data needed 
to be converted from DB MASTER file format to ASCII so that 
Icould direct connect the Mac and the //e together. DB MASTER 
utilities includes an export utility which would convert files to 
either DIF or a "One Field per Line" format. The utilities 
converted my mail list from my Sider hard disk to about 50 143K 
floppy disks (UGH!). Next the ASCII needed to be converted 
from Apple // ASCII to "the rest of the world" ASCII format. 
ASCII EXPRESS telecommunications software provides a 
conversion utility for doing this (If they didn't I'd have to use my 
own Basic program to convert it myself. Next each disk was 
converted via direct null modem connection to the Mac. Whew! 

To make a long story (and many hours) short, the mail list 
was now on the Mac, but somehow during the process some 
control characters were intermixed in the files. Omnis 3 would 
not read the files with these control characters so it was BASIC 
to the rescue. There аге 128 standard ASCII characters of which 
the first 31 characters are control characters, traditionally used 
for teletype terminals. The problem was easily solved by writing 
a Basic routine to read in the file, filter out the bad characters and 
rewrite the file. Compile the program to speed it up! 


Control Character Filter 
“ eMacTutor, 1988 

' By Dave Kelly 

‘ MSBASIC 


x$=F ILES$( 1, "TEXT^) 

IF x$="" THEN END 

OPEN x$ FOR INPUT AS #1 

OPEN “Filter Output” FOR OUTPUT AS #2 
WHILE NOT EQFC 1) 
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EN 


Char$=INPUT$C 1, 1) 
IF ASCCCher$2»-32 THEN PRINT #2,Char$; 
IF Сһаг%-СНЕК 13) THEN PRINT #2, Снаг$; 
WEND 
CLOSE 81 
CLOSE #2 


That’s ok for simple filtering. Things may need to be more 
complex if the original file contains unexpected characters in it. 
Recently, I came across the need to convert data stored in a 
FileMaker Plus file in order to do some simple, but unusual 
calculations. As drafting is done for test equipment the progress 
is logged into a FileMaker Plus file. Each drawing number is 
entered with its own charge number and the date is entered 
indicating the start or completion of stages of the drawing 
process. Occasionally the boss (who is always right because he 
is the boss) wants a drawing status report according to charge 
number (there are multiple drawings per charge number). File- 
Maker Plus will give the total number of drawings but only after 
searching for each of the charge numbers and dates individually. 
BASIC to the rescue. 

The Drawing Count program was written to count progress 
of each of the charge numbers. A file is opened for input and 
another file for output. Each field was previously exported to a 
BASIC formatted file and is read by the Basic program in the 
same order which it was written. The charge number is saved, but 
each of the date fields is replaced by a flag (0 or 1) which 
indicated if there was anything in the date field. These Os and 1s 
are added together to get the totals after the data is sorted. The sort 
routine could have been beefed up but, for a “quick and dirty” 
program, it does the job. The program was compiled with the MS 
Basic compiler which provided adequate speed results. 

If you are wondering why ZBasic wasn’t used here, so am I. 
Actually, I ran into a small problem which appears to be a bug 
with ZBasic 4.01 while reading the FileMaker Plus exported text 
files. Although ZBasic’s INPUT# statement is supposed to read 
data from the file until a carriage return, «COMMA», End-Of- 
File, or 255 characters are encountered, when ZBasic saw a 
comma followed by a carriage return, the null between the 
comma and carriage return was skipped and the next field (from 
the next record) was read in. The data looks like this: 


“ITEM1”,"ITEM2","ITEM3", 
"ITEM4A","ITEMS","ITEMe","ITEM7" 


The null field after item3 was skipped and ІТЕМА is read in. 
This is how data is formatted when dumped in comma delimited 
format as with FileMaker Plus. Sorry, Zedcor. 
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COORDINATE WINDOW 

DEF OPEN “TEXTDAVE’ 

BREAK ON 

f ilenane$-F ILES§C 1, “TEXT”, , vo18) 
IF filename$="" THEN END 

OPEN "I^, 1,f ilename$, ,vo1$ 
INPUT 81,А%,8%,С%,0% 

PRINT @(1, 1224$,B$,C$,0$ 

CLOSE ! 


Another file conversion problem to deal with involves the 
conversion of text which has been dumped from text fields. 
FileMaker Plus, for example, inserts an end of line mark at the 
end of each line when it exports data to a file. When the data is 
read into another program which doesn't use the end of line 
character to mark the end of lines (because the text is word 
wrapped and reformattable). If you read the FileMaker text field 
into Double Helix II for example, the end of line character shows 
up in the text field as an undefined character (a box). The filter 
method explained above can find these characters if you know 
what character it is. 

Fortunately life is much easier for converting data these days 
than it was even five years ago. Now I use file formats like DIF 
and SYLK whenever I can when converting between programs 
that support both formats. The transfer goes a lot less painfully 
when the format is well defined as the DIF format is. For those 
not familiar with DIF, it is called the “Data Interchange Format” 
and was originally designed to by Software Arts (are they still 
around?) to transfer data from Visicalc (the father of all spread- 
sheet programs). The file is completely ASCII but has header 
information added to help maintain data integrity. (This saved 
me a few times). This means that the file will undoubtedly be 
larger than without DIF formatting so be sure that you only use 
it for file transport rather than data storage especially if your disk 
free space is critical. SYLK is Microsoft's format. Most 
Microsoft products and a few data base programs such as Omnis 
3 and FileMaker Plus support SYLK format. The best way to 
figure out how these work is to analyze some sample data from 
a program that exports in one of these formats. 


“ Drawing Count Program 

‘ Converts Drawing Log Data created by FileMaker Plus 

‘ and computes total number of drawings under each date 
^ By Dave Kelly 

' 01988 

‘MS BASIC 


DIM Сһагде$ 1800), Date 1( 1980), Date2( 1080), Date3¢ 1000), 
Date4C 1000) 
DIM tCharge$(20),tDate1(20),tDate2(20),tDate3(20),tDate4(20) 
f i lename$=F ILES$C 1, "TEXT^) 
IF filenane$-"^ THEN END 
OPEN “I”, 1,filename$ 
OPEN “0*,2,*Drawing Count DATA" 
PRINT 
count=8 
CALL MOVETOC 10,302 
PRINT “Now Reading in Records...” 
WHILE NOT EOFC1) 
count=count+ 1 
CALL MOVETO (10,50) 
PRINT count 
Charge$Ccount )="” 


ig="" 
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А4-”” 

(4-”” 

S$="" 

INPUT# 1, Charge$Ccount), i$, A$,C$,S$ 

IF LENCCharge$(count))»8 THEN 

IF RIGHT$CChargef$Ccount?, 12-72” THEN 
Charge$Ccount?:M ID$CCharge$Ccount? ,LENCCharge$Ccount?)2- 
4,4) 


E 
Charge$(count ):RIGHT$SCCharge$Ccount?, 4) 
END IF 

END IF 

IF ЕМ№ 1$ ›0 THEN Date 1(count)=1 ELSE Date 1¢count)=8 

IF LENCA$)>8 THEN Date2(count)=1 ELSE Date2(count )=@ 

IF LENCC$)>@ THEN Date3(count)=1 ELSE Date3(count )=0 

IF LENCS$»»0 THEN Date4(count)=1 ELSE Date4(count )=0 
WEND 
CALL MOVETOC 10,70) 
PRINT “Now Sorting Data...” 
CALL Sort(count, Charge$(), Date 1(), Date2(), Date3(), Date4()) 
k=0 
FOR j=1 TO count 
IF tCharge$(k)OCharge$(j) THEN к-к1 
tCharge$(k)=Charge$(j) 
tDate 1(К)={Ша{е 1Ck2*Date1Cj) 
tDate2Ck)2tDate2Ck)*Date2( j) 
tDate3Ck22tDate3Ck)*Date3( j) 
tDate4Ck22tDate4Ck)*Date4( j) 
NEXT j 
CALL MOVETOC 10,92) 
PRINT “Now Writing to File...” 
PRINT#2, "Charge? Date 1 Date2 
FOR i=1 TO k 
tDate1Ci )=tDate 1¢ i )-tDate2C i) 
{Оа{е2(1 =tDate2Ci )-{Оа{е3 (1) 
{Оа{е3 (1 )={Ба{е3 (1 )-tDate4¢ i) 
PRINT #2, tCharge$C i5, tDate1Ci2, tDate2Ci), {Оа{е3( 1), tDate4Ci) 
PRINT tCherge$Ci2, tDate1Ci2, tDate2C i2, tDate3C i2, tDate4Ci) 
NEXT i 
CLOSE 81 
CLOSE #2 
PRINT^Click to continue..." 
ED MOUSEC22«» 1:WEND 


Dete3 Date4" 


SUB Sort(count, Charge$ CO, Date 1€),Date2(), Date3C), Date4O) 
STATIC 
flips=1 
WHILE flips 
flips=0 
FOR i=2 TO count 
IF Charge$Ci-1)) Charge$(i) THEN 
flips=1 
SWAP Charge$Ci- D, Charge$Ci) 
SWAP Datel1Ci-12,DatelCi) 
SWAP Date2Ci- 1D,Date2Ci) 
SWAP Date3Ci- 12, Date3Ci) 
SWAP Date4Ci- 12,Date4Ci) 
END IF 
NEXT 
WEND 
END SUB 


HYPER-CORNER 

The new update disk for HyperCard version 1.1 contains a 
read me stack with three new buttons pertaining to importing and 
exporting data. If you don't have the new update you can get it 
from your Apple dealer. Version 1.1 is supposed to fix some bugs 
that "bugged" some of us. 

Theread me stack gives directions for using the new buttons, 
but I'll try to explain them a little bit here. To try them out, create 
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Hard Disk:MacTutor®:MAY В8В:1трог1/Енрогї Demo custom library of XCMDs 


Field 2 


Fig. 1 Hyper Dialog 


a new stack with a few fields in it such as the one I created; see 
fig. 1. 
HyperCard Import/Export 

The arrow keys were added from the Button Ideas stack to 
make it easy to check out the data, but you will need to remember 
the command 1,2,3,4 keys that move you from card to card or you 
may use the arrow (or option-arrow) keys to move from field to 
field. 

The most useful of the buttons is the Export Data button. It 
allows you to select the background fields you wish to export and 
the delimiters separating the fields and records. Most database 
programs will read the tab delimited records (with carriage return 
between each record). NO, the export button will not export card 
fields, only background fields. That is understandable since the 
output needs to be consistent. 

Ifound that the best way to see how the buttons work is to try 
them out. Clicking on the Export Data (or Export Text) button 


Export which background fields: 


Fig. 2 Export Dialog 


will produce this dialog which will let you select the background 
field you desire to output. (See figure 2) 
Selecting the Fields for Export 
After selecting the All button or after selecting which of the 
background fields you want to export, you specify the file name 
to export to. A dialog comes up to ask you for the name of the text 
file to export in figure 3. 
Selecting a Filename for Export 
There is an XCMD around someplace for calling the Stan- 
dard File Dialog which would be better to substitute for this 
dialog. The problem with XCMD routines for general use is that 
not everyone has them. It would be best to set up your own 
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to use in your own stacks. 

І ran into no difficulty 
getting my data to export to 
a file. You can examine 
your data with a word proc- 
essor to see how the text file 
looks when the data has 
been exported. I like using 
MS Word for examining 
this kind of file because you 
сап view all the tabs and 
Carriage returns using the 
Show { menu item. 

The Import Button 
works well too, except that 
you can't import data into 


Name or pathname of tent file to export to: 


Hard Disk:Export Tent 


Fig. 3 Editable Dialog 


existing background fields. It creates the background fields on 
the fly. Perhaps someone out there could create a button script 
that will allow you to specify which field you would like to be the 
first, second and so on field to be read in. AT LEAST, now these 
buttons are included with HyperCard. At first, it may appear that 
the import didn’t work, but if you read the instructions in the read 
me stack, it explains that the new background fields are created 
one on top of another. To see the fields you will have to peel them 
apart. (see figure below) 
Imported Fields 

Ideally, the importing will be done first thing before the 
stack layout is designed if possible. Importing/Exporting of text 
with HyperCard has been one of the weak links. With all the 
interest in HyperCard these days, there should be more XCMD 
routines and tools we can use to improve the usefulness of 
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Basic School 


Hierarchical Menus & Color Notes Menu 


Hierarchical Menus in ZBasic 


Hierarchical menus (also known as submenus) are possible 
inZBasic with a small amount of sweat. Hierarchical menu items 
have the small filled black triangle pointing to the right in many 
of the newer application programs that are coming out now. This 
month I will show you how youcan implement them in your own 
ZBasic source code. 

There are a few standard guidelines for using submenus 
which you can find in The Macintosh User Interface Guidelines 
found in Vol. 5 of Inside Macintosh. In the pull-down menu 
structure of the Macintosh, it was originally intended that the user 
could quickly scan through all of the menus and know the 
function of all the menu items. Therefore, it is strongly recom- 
mended that submenus only be used for lists of related items. 
You should try to only use one level of hierarchical menus 
although it is possible to go several levels. 

The concepts of submenu programming is fairly simple and 
easy toimplement. However, implementing submenus in ZBasic 
without some understanding of how things work will probably 
frustrate some of the average Basic programmers out there. The 
first thing we have to do is throw away the ZBasic event loop and 
event handling statements and set up our own GETNEXTE- 
VENT loop. This sounds difficult to some of you, but actually it 
solves some of the problems inherent in ZBasic that I've been 
pulling my hair out over for the past year or so. In this month's 
sample program I even went a step further by defining some of 
the menus and the main window using MENU and WIND 
resources. You can refer back to my GETNEXTEVENT ZBasic 
shell program in September 1987 MacTutor. This will give you 
the program shell to start with. 

First create the window resource. Any window type will do 
for this example. I chose the rDocProc type window which has 
a ProcID number 16. To create the WIND resource, open 
ResEditand select New from the File menu and type in the WIND 
resource type. Then select New to create a resource and type the 
following parameters into your window (as shown in the ResEdit 
Window in figure 2): 


boundsRect 54 78 280325 
procID 16 

visible True 

goAway False 

refCon 0 


title Hierarchical Menu Sample 


Change the WIND ID to 29414 (or any other unique number) 
by selecting Get Info from the File menu. Now the WIND 
resource is created. This window will be used by the program to 
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Fig. 1 Our hierarchical menu example in ZBasic 


output confirmation that everything works. 

The menus are just as simple to create with ResEdit as the 
WIND resource was. The parameters for each of the menus is 
shown in the window dumped from ResEdit which are included 
here. Two menus are created with ZBasic Menu statements 
which are not included as resources. Actually, it would probably 
be better to use all toolbox calls instead of ZBasic Menu state- 
ments because we could be in complete control of all the menus. 
MENU id 255 is the Apple menu created with the APPLE MENU 
statement in ZBasic, but it is very automatic and you have to have 
desk accessories whether you like it or not. If you created your 
own, you could exclude any part you didn’t want, but you would 
have to control every little thing that happens. MENU ID 2 is 
created with the ZBasic EDIT MENU statement. This is the 
easiest way to make an Edit menu. MENU ID 134 is the File 
menu. It contains only one menu item, "Quit". — 

MENU ID 135 is the Format menu which is the main menu 
which the submenus will be attached. The Format menu contains 
two items, “Style” and "Font" which will each have submenus. 
Now comes the fun part. To attach a menu we first set the "key 
equiv” for the menu item to $1B. This will put the black filled 
triangle in the menu. А $1B is ASCII character 27, the ESCAPE 
key. If you have an Extended keyboard you will have no trouble 
producing this character by typing “esc”. Typing CTRL-[ will 
also produce the ESC character. However, I haven't found a 
good way to produce ESC using the MacPlus or earlier key- 
boards; anybody know how??. Next the ID of the submenu is put 
in the mark Char field. Actually, you enter the character which 
has the ASCII value of the ID of the submenu. In the Style menu 
the ASCII value of “à” is 136. This character is entered by using 
the “орНоп-`” then “а”. The Font menu has submenu with 
ID=137 so the mark Char is “А” which is entered by typing 
“option-i” and the “а”. You should examine the ResEdit win- 
dows shown here if you need more help understanding this. 

After the MENU and WIND resources are complete, the 
program can be compiled. You will need to compile the program 
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= === WIND 10 = 29414 from HMENU.RES КЕ == 
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Fig. 3 Menu Resource 


as an application and install the MENU and WIND resources 
before running the program or unexpected results will occur. 
Remember that the program needs to have the resources in order 
to work properly. Be sure that the resources are installed by 
running ResEdit immediately after compiling. It would be nice 
if ZBasic would install a resource file for you as in “r 
development languages. Maybe they will add this capability 
‚ someday. 

The program really doesn’t do anything except respond to 
the menu and print to the window which menu was selected. 
There are a few left over functions that were originally part of the 
GETNEXTEVENT shell program. The shell could be expanded 
to work with other applications you may like to do. 

An alternative to using ResEdit is to create your resources 
with RMaker, as shown in the program listing. Once the re- 
sources are compiled, ResEdit can be used to move the resources 
from the RMaker output file into the ZBasic compiled file. 
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Sorry State of Mac Basics 

Thus far, the Mac II has been out overa year and as of the date 
of this writing, there is still no Basic released which fully 
supports all the new ROM capabilities. Even the method I’ve 
shown here is a work around because of the way that ResEdit has 
to be used. It still holds true, however, that ZBasic has the most 
features and is faster than any of the competitors. Microsoft still 
has no new updates of MS Basic. And with all the bugs in the 
compiler, Absoft doesn’t want to add any new features till the old 
ones are fixed. Somebody is walking around with blinders on and 
doesn’t even know it. From the response I’ve seen, most people 
are dissatisfied with all the Basic products that are currently 
released. There are still some possibilities coming up... True 
Basic 2.01 was released this week. We will be taking a good hard 
look at the new True Basic in upcoming issues. The grapevine 
says that Microsoft is readying a new release for sometime? All 
I сап say is that I hope they are listening to all of us and what we 
are screaming for. [Note that True Basic 2.0 was found to be 
defective shortly after shipment, and the company has upgraded 
immediately to 2.01. It seems that a memory management bug 
exists in 2.0 that is actually hidden by the presence of the 
Macsbug debugger, which nearly all their beta testors were 
using. When they tried the product without Macsbug installed, a 
problemwas found that seems to prevent True Basic from picking 
up on mouse and keyboard events properly during program 
execution. We discovered it when we noticed the demos would not 
stop without powering down the Mac. So be sure to check that 
your upgrade diskis version 2.01 апаа word of warning to other 
developers, that the presence of a debugger may be altering or 
hiding potential memory manager bugs. -Ed] 

By the way, my daughter helped to discover a undocumented 
feature of ZBasic. She was quietly invading my Mac II (whenI 
wasn't looking) while I had ZBasic running and happened to 
press the arrow keys. Well... it turns out that the down arrow key 
lists the next sequential program line. The uparrow key prints the 
previous line. Right arrow lists the last line and Left arrow lists 
the first line. Interesting, but I prefer to do all my editing using an 
editor. Га like to say I like using the built in editor the best, but 
it still doesn’t quite work right. 


True Basic 2.01 & Color Models 

One of the neat features of the new True Basic 2.01 is that it 
supports Macintosh II color including palette animation. In fact, 
the palette animation article we did last month in MacTutor can 
be done in just a few lines in True Basic! And a neat Mac touch 
they have added is that the output window for True Basic is saved 
and refreshed and can be written to disk as a PICT2 resource, 
unlike MS Basic, which “forgets” how to update the output 
window after a program runs. To help us get up to speed on color 
processing on the Mac, here are some notes on color types. 

Along with color and the Mac II there also comes new 
terminology. I’m sure there are many of you that either haven’t 
wanted to or have had no opportunity till now to know about the 
various color models that exist. Most of us have heard of RGB, 
some for the first time when they bought their Mac II with RGB 
monitor. RGB is yet only one of several color models being used 
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іп the computer graphics industry. Some other color models 
include: CMY, YIQ, LAB, HSL, HSV, and HSI Color Models. 

I will attempt to explain them from the few things that Ihave 
read on the subject. Each model has its advantages and disadvan- 
tages. In general the color models have been formed to assist the 
user in selecting one of the 16 million colors. 


RGB 
RGB is directly related to the hardware involved in color 
displays. Most of us are familiar with this from using the Color 
Picker package to select colors on the Mac II. The Red, Green, 
and Blue values are represented as long integers, which are 
converted into signals driving each of the color guns in the CRT 
(one for each color). The RGB model is easier for the program- 
mer to implement because it is directly related to the hardware. 
But it may not be the easiest for the user to use unless he/she 
understands the RGB model. The other color models are always 
converted to RGB then the hardware uses a Color LookUp Table 
(CLUT) to determine which color to display. Also notable about 
the RGB model, when the values of RGB are equal (К = G = B) 
the CRT phosphor chromaticities are balanced so that gray is the 
result. The brightness or darkness of grey is determined by the 
amplitude of the RGB components as they effect the color guns 
of the CRT. 
HSV 
HSV stands for Hue, Saturation and Value. The Hue 
associates the color with a value in the color spectrum, Saturation 
represents the vividness of the color with pure colors (such as 
red, green, and yellow) being called fully saturated colors and 
grays being called desaturated colors, the Value represents the 
lightness or darkness of a color. The Brightness field of the 
Macintosh Color Picker dialog is the equivalent of the HSV 
value. The Color Picker primarily works using the HSV model. 
The RGB values are shown also, but only users that understand 
both color systems will understand how to the HSV and RGB 
values relate. The RGB system is given so that the user will have 
an alternate system to choose from just in case the user is familiar 
with another system other than HSV. 
YIQ 
The YIQ model has been in use as a television broadcast 
standard since it was adopted in 1953 by the National Television 
Standards Committee (NTSC). The purpose of the YIQ model 
was to provide a means to encode color information in such a way 
as to be compatible with black and white transmission. Three 
components of the YIQ model are: Y, an approximation of 
luminance; I, chrominance information along a blue-green to 
orange vector; and Q, chrominance information along a yellow- 
green to magenta vector. A conversion formula was defined by 
the Commission Internationale de L’Eclairage (CIE): 


R 100 095 0.62 Y 
С| = | 1.00 -0.28 -064| ° |I 
B 1.00 -1.11 1.73 Q 
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Тһе CIELAB model is ап international standard for регсер- 
tual uniformity. This one is difficult to explain, and probably just 
as difficult to understand. This model relates the color differ- 
ences that a human perceives as being equal Euclidean distances 
in CIELAB space. This model only approaches its objective 
because of the varying perception of color that humans have. It 
is said that CIELAB is better for making fine adjustments in the 
color selection process. 

HSI 

HSI processing can be less complicated than other models. 
Hue values can provide the basic for quantizing and interpreting 
the color of objects. Tinting, retouch, and special effects can be 
produced by modifying hue values, or saturation values. Using 
HSI, all methods for processing and analyzing monochrome 
images can be applied directly to color images. 

HSL, HSV 

Idon'tknow the difference between HSI, HSL, HSV models 
but they have been referred to as separate models in some of the 
things I've read. HSL is mentioned in Inside Macintosh, Vol 5, 
but not explained. I'll leave the explanation for a future column. 
I would appreciate any comments in the form of letters that would 
explain this. 

Conversions are available in the Macintosh Color Picker 
package described in Inside Macintosh, Vol. 5 for some of the 


color models. They are: 
PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); 


PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); 
PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); 
PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); 
PROCEDURE CMY2RGB (hColor: HSLColor; VAR rColor: RGBColor); 
PROCEDURE CMY2RGB (rColor: RGBColor; VAR hColor: HSLColor); 
See Inside Macintosh for more information on the conver- 
sions. It is sufficient here to know that the conversions exist. 
Other information on this subject can be found in the 
following sources (I have not seen all of these sources myself): 

1. APPLE COMPUTER, INC., /nside Macintosh, Vol S. 

2. SCHWARZ, MICHAEL W., COWAN, WILLIAM B., and 
BEATTY, JOHN C. An Experimental Comparison of RGB, 
YIQ, LAB, HSV, and Opponent Color Models, ACM Transac- 
tions on Graphics, Vol 6, No.2, April 1987, Pages 123-158. 

3. BECKER, R. A. and CHAMBERS, J. M. S-An Interactive 


Environment for Data Analysis and Graphics. Wadsworth, 
1984. 


5. BERK, T., BROWNSTON, L., and KAUFMAN, A. A new 
color-naming system for graphics languages. IEEE Comput. 
Graphil. Appl. 2,3 (May 1982), 37-44 

6. BERK, T., BROWNSTON,L., and KAUFMAN, А. A human 
factors study of color notation systems for computer graphics. 
Commun. ACM 25,8 (Aug. 1982), 547-550) 

7.BOYNTON, R. M. Human Color Vision. Holt, Rinehart and 
Winston, New York, 1979. 

8.CIE. Recommendations on Uniform Color Spaces, Color- 
Difference Equations, Psychrometric Color Terms. Bureau 
Central de la CIE (Supplement 2 of CIE Publication 15 (E- 
1.3.1) 1971), 1978. 
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9.РОГЕУ, J. D., and VAN РАМ, A. Fundamentals of Interac- 
tive Computer Graphics. Addison-Wesley, Reading, Mass. 
1982. 

10. HURVICH,L. M. Color Vision. Sinaur, Sunderland, Mass., 
1981. 

11. WYSZECKI, G., and STILES, W.S. Color Science: Con- 
cepts and Methods, quantitative Data and Formulae, 2nd ed. 
Wiley, New York, 1982. 

12. JOBLOVE, G. H., and GREENBERG, D. P. Color spaces 
for computer graphics. Comput. Graph. 12,3 (Aug. 1978), 20- 
25. 

13. MUNSELL, A. H. A Color Notation. Munsell Color 
Company, 1939. 


REM Hierarchical Menu Demo 

REM MacTutor 1988 

REM Ву Dave Kelly 

WINDOW OFF 

COORDINATE WINDOW 

DEF MOUSE-- 1 

everyevent=-1:REM ALL events mask 

False=0: True=NOT False 

DIM dragRect%(3) 

‘Find out monitor size just in case we need it 

CALL GETWMGRPORTCWMgrPor t&) 

PortTop-PEEK WORD(WMgrPort&*8) 

PortLef t-PEEK WORDCWMgrPor t&+ 10) 

PortBottom-PEEK WORDCWMgrPor t&* 12) 

PortRight-PEEK WORDCWMgrPor t&+ 14) 
ALL 


C 
SETRECT(dragRect%(8),PortLef t+ 10, PortTop* 10, PortRight- 
10, PortBottom- 10) 
REM Setup the EventRecord 
myEvent$-0:REM ‘what’ is first variable 
message&=0 
when&-0 
where-0:REM y coordinate of point is first 
wherex- 
modif iers-g 
app lemark=&H 14 
whichwindow&=8 
charCodeMask&-VALC^&HOOO009FF ^) 
keyCodeMask&= VALC^"&HOODOFF 00^) 
myWindow&-FN GETNEWWINDOW(C29414,0,- 1) 
CALL SETPORTCmyW indow&) 
TEXT 2, 12,0,0 
CLS 
GOSUB "SetUpMenus" 
FLUSHEVENTS 
*EventLoop^: REM Main Event Loop 
0 


D 
CALL SYSTEMTASK 
LONG IF FN GETNEXTEVENTCeveryevent, myEvent) 
SELECT myEvent$ 
CASE 0:ВЕМ No Event 
CASE 1:REM mousedown 
wResult-FN FINDWINDOW where, whichwindow&) 
SELECT wResult 
CASE 0:ВЕМ inDesk (do nothing) 
CASE 1:REM inMenuBar 
mResult&-FN MENUSELECT where) 
theMenu=FN HIWORDCmResul t&) 
theItem-FN LOWORD(mResu1t&) 
SELECT theMenu 
CASE 255 
GOSUB “арр1е10” 
CASE 134 
GOSUB "f ileID^ 
CASE 2 
GOSUB “editID’ 
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CASE 136 
60508 "StyleID^ 
CASE 137 
GOSUB "FontID^ 
END SELECT 
CALL HILITEMENUC2) 
CASE 2:REM inSysWindow 


CALL SYSTEMCLICK(myEvent, whichwindow&) 


CASE 3:REM inContent 

CASE 4:REM inDrag 
CALL DRAGWINDOW(myWindow&, where, 

dragRect$(0)) 

CASE 5:REM inGrow 

CASE 6:REM inGoAway 
Byte-FN TRACKGOAWAYCmyW indow&, where) 
IF Byte THEN PRINT" 


CLOSEWINDOW(myW indow& 2^ 


END SELECT 
CASE 2:REM mouseup 
CASE 3:REM keydown 
PRINT^key-down^ 
charCode&-FN BITAND(Cmessage&, charCodeMask&) 
keyCode&-FN BITAND(message&, keyCodeMask& ) 
keyCode&-FN BITSHIFTCkeyCode&, -8) 
PRINT "Charcode-^;charCode& 
PRINT “Keycode=”;keyCode& 
CASE 4:REM keyup 
CASE 5: REM autokey 
CASE 6:REM updateEvt 
CASE 7:REM diskEvt 
CASE 8:REM activateEvt 
CASE 10 REM networkEvt 
CASE 11 :REM driverEvt 
CASE 12 :ВЕМ epplEvt 
CASE 13 :REM app2Evt 
CASE 14 :REM app3Evt 
CASE 15 :REM app4Evt 
CASE ELSE 
END SELECT 
END IF 
UNTIL theEnd 
*SetUpMenus"^ 
APPLE MENU “About Sample..” 
AboutHandle&-FN GETMHANDLE(255) 
FileHandle&-FN GE TMENUC 134) 
CALL INSERTMENUCF i leHandle&, ø) 
EDIT MENU 2 
EditHandle&-FN GE TMHANDLEC 130) 


FormatHandle&-FN GETMENUC 135): Get Format Menu Handle 


StyleHandle&-FN GETMENUC 136): Get Style Menu Handle 
FontHandle&=FN GETMENUC 137): Get Font Menu Handle 
CALL INSERTMENUCFormatHandle&, 8) 
CALL INSERTMENUCStyleHandle&,-1): “Style Menu 
CALL INSERTMENUCFontHandle&,-1): Font Menu 
CALL ADDRESMENU(CFontHandle&,CV IC"FONT^2) 
‘ Check default font in Font menu 
fontent$-FN COUNTMITEMSCFontHandle&) 
def aul tfont$="Geneva” 
FOR 1=1 TO fontcnts 
CALL GETITEMCFontHandle&, i, item$) 
ШШ s i THEN Oldmitem=i:i=fontcnt%+1 
XT i 
CALL CHECKITEMCFontHandle&,O1dmitem, True) 
TextStyle-0 
Р1а1п=@ 
Bold=1 
Italic=2 
Under! ine=4 
Out] ine=8 
Shadow= 16 
Condense=32 
Extend=64 
just^e 
CALL DRAWMENUBAR 
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RETURN 
*eppleID^ 
CALL GETITEMCAboutHandle&, theI tem, Var$) 
PRINT Var$ 
nrefNun-FN OPENDESKACCCVar$) 
CALL SETPORTCnyWindow&k) 
RETURN 
"fileID^ 
END 
RETURN 
*editID^ 
IF NOT FN SYSTEMEDIT(theItem-1) THEN RETURN 
SELECT theItem 
CASE 1:REM undo command 
CASE 3:REM cut command 
CASE 4:REM copy command 
CASE 5:REM paste command 
CASE 6:REM clear command 
END SELECT 
RETURN 
*StyleID^ 
CALL GETITEMCStyleHandle&, theIten, Var$) 
CLS: PRINT Var$;” selected” 
RETURN 
*FontID^ 
CALL GETITEMCFontHandle&, theIten, Var$) 
CLS: PRINT Ver$;" selected” 
RETURN 


х ZBasic.R 
*Basic.RSRC 


Type ZBDK = STR 
‚@ 
€ Demo by Deve Kelly \@Dver 1 JUN 1988 
Type FREF 
, 128 
APPL 0 


Туре BNDL 


x —— Multifinder events — 
* bit 15 = switcher save screen 


* bit 14 = accept suspend resume events 

* bit 13 = switcher enable option switch 

* bit 12 = сап do background on null events 
* bit 11 = multifinder амаге 


Type SIZE = GNRL 
71 


.H 
4000 ;; $4000 - bits 14 set 
L 


128000 ;; (for 150K recomended) 
L 

80000 ;; (for 80K minimum) 

I 


Type ALRT 
‚1 (0) 
80 80 205 400 
1 
1165 


Туре ALRT 
‚2 (0) 
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80 55 205 425 
2 
1165 


Туре ALRT 

‚3 (0) 
80 55 205 425 
3 


7765 


Туре МЕТ 

,4 (0) 
80 55 205 425 
4 


1165 


Туре МЕТ 

‚5 (0) 
30 250 82 502 
5 


1165 


Туре МЕТ 
,129 (0) 

80 80 200 400 

129 

5555 


Туре ALRT 
‚ 130 (0) 
80 80 200 400 
130 
7765 


Туре ALRT 
‚ 158 (0) 
80 55 200 425 
150 
1165 


Туре МЕТ 
,152 (0) 

80 80 200 400 

152 

7765 


Туре DITL 
,1 (9) 
5 


Button 
15 245 40 305 
Ok 


staticText Disabled 


55 10 70 290 
^ 


staticText Disabled 


T2 10 87 290 
^] 


staticText Disabled 


89 10 104 2090 
2 


staticText Disabled 
106 10 121 290 


^3 


Туре DITL 
‚2 (0) 
б 
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Button 
15 295 40 360 
Ok 


Button 
55 295 80 360 
Cancel 


staticText Disabled 
55 10 70 290 
^9 


staticText Disabled 
712 10 87 290 
^1 


staticText Disabled 
89 10 104 290 
^2 


staticText Disabled 
106 10 121 290 
^3 


Type DITL 
‚3 (0) 
6 


Button 
15 295 40 360 
Yes 


Button 
55 295 80 360 
№ 


staticText Disabled 
55 10 70 290 
^g 


staticText Disabled 
T2 10 87 290 
^1 


steticText Disabled 
89 10 104 290 
72 


staticText Disabled 
106 10 121 290 
^3 


Туре DITL 
‚4 (0) 


Button 
55 295 80 360 
Cancel 


Button 
15 295 40 360 
Ok 


staticText Disabled 
55 10 70 290 

~g 
 staticText Disabled 
12 10 87 290 

1 


staticText Disabled 
89 10 104 290 
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^2 


staticText Disabled 
106 10 121 290 
^8 


Tgpe DITL 
,9 (0) 
4 


Button 
6 210 45 246 
Ok 


staticText Disabled 
10 65 25 205 
“0 


staticText Disabled 
26 65 41 130 
At Line 8 


staticText Disabled 
26 130 41 205 
^1 


Туре DITL 
,129 (0) 
3 


Button 
15 245 40 305 
OK 


staticText Disabled 
48 10 64 300 
^0 


staticText Disabled 
66 10 82 320 
^1 


Туре DITL 
, 130 (0) 
2 


Button 
15 245 40 305 
OK 


staticText Disabled 
48 10 64 300 
Not Enough Memory! 


Туре DITL 
,150 (0) 
5 


Button 
55 295 80 360 
Stop 


Button 
15 295 40 360 
Continue 


staticText Disabled 
48 10 62 290 
“0 


staticText Disabled 
66 10 80 290 
*1 


StaticText Disabled 
84 10 98 290 
^2 


Туре DITL 
‚152 (0) 


Button 
15 245 40 305 
Ok 


staticText Disabled 
48 10 62 300 
The Printer Driver Could not be Opened. 


staticText Disabled 
66 10 80 300 
You will not be able to print anything. 


* Menus 
Туре MENU 
,135 (0) 
Format 
Style /\1B!\88 
Font /\1B!\89 


Type MENU 
, 134 (0) 
File 

Quit 


Type MENU 
‚ 136 (0) 

Styles 
Bold /B 
Italic /I 
Underline /U 
Outline /0 
Shadow /S 


Type MENU 
, 137 (0) 
Fonts 


* A Window template 
Type WIND 

‚29414 (0) 
Hierarchical Menu Sample 
54 78 288 325 
Visible NoGoAway 


16 
0 m 
v 
Туре ICN! = GNRL So, 
‚128 (8) == 
H 


0001 0000 0002 8000 0004 4000 0009 A000 
0013 1000 0026 0800 004С 0400 0098 0200 
0133 0100 0267 8080 04СЕ 4040 09A9 (020 
1310 8010 2688 0008 4C64 3Ғ04 8822 4082 
4015 8041 2008 3022 1005 C814 081Е ТЕР 
0402 3005 0201 0007 0100 8005 0080 6007 
0040 ІҒЕ5 0020 021Ғ 0010 0407 0008 0800 
0004 1000 0002 2000 0001 4000 0000 8000 
x 


0001 0000 0003 8000 0007 COO 000Ғ Е000 
001Ғ Ғ000 003Ғ Ғ800 007F FCO GOFF ҒЕ00 
@1FF FF00 ОЗЕР ЕҒ80 O7FF FFCO OFFF FFEO 
IFFF FFFØ 3FFF FFF8 TFFF ЕРЕС FFFF FFFE 
TFFF FFFF 3FFF FFFE 1FFF FFFC OFFF FFFF 
ОТЕЕ FFFF Ø3FF FFFF O1FF FFFF 00ЕҒ FFFF 
007F FFFF 003F FEIF 001Ғ ҒС07 000Ғ Ғ800 
0007 FOO 0003 Е000 0001 С000 0000 8000 
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Basic School 


The new and improved version of True Basic (ver. 2.01) has 
just recently started shipping. Some of the new features include: 
built in support for full color and PICT format images, 68881 
coprocessor support, and a more structured environment using 
modules and workspaces. True Basic also now includes the 
Runtime package (which used to cost a few hundred dollars), but 
they are packaging the Macintosh Developer's Toolkit sepa- 
rately. The toolkit contains all of the libraries which are essential 
for making “real” Macintosh programs (menus, windows, con- 
trols etc). Itisobvious to any dedicated Macintosh developer that 
this package should have been included with the True Basic 
"Basic" package. However, itis true that when True Basic is sold 
to a school as a training tool, there is not much need for the 
Macintosh libraries. 

This month, I am not going to do an in depth analysis of True 
Basic 2.01 (Basic Wars, part ??). ГІ save that for next month. I 
would like to show off some of True Basic's new features with 
respect to Macintosh II color. I'm still impressed by Mac II's 
color! 

True Basic has its own unique set of statements for using 
color. The SET COLOR n statement (where n is a number from 
010255) setsthe drawing pento thecolor selected. Thena PLOT 
or some other graphics command may be given to operate in the 
selected color. Selecting color is not really very unique. ZBasic 
uses a similar statement (COLOR=n) to select colors. 

The Palette Manager is responsible for monitoring and 
establishing the color environment on the Mac II. The system 
provides a default palette of colors which applications may use 
as desired. The default palette is a set of standard colors which 
may be selected. Color Quickdraw will match the selected color 
as best as it can, but there may be times when more shades of a 
particular color are desired than are available in the default 
palette. 

Most video devices including the Mac II video card use an 
indexed color model. Each pixel value in the video device's 
memory corresponds to an indexed value in the color table. The 
color display card uses the RGB value found in the look up table 
to display the desired color. There are several advantages to 
using this indexed display method. One is that it is faster. Also, 
itallows color animation to be used. In color animation, the index 
value is changed to change display colors; the pixel color itself 
is not changed. You can especially see the effects of this when 
using Pixel Paint or Modern Artist and changing the palette using 
the application. Another way to see the effects of changing the 
palette is by using the Colorizer software, by Palomar. This is 
recommended to any Mac II user that wants to make better use of 


color on the Mac II. [The Colorizer and the PICT Dective are | 
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Dave Kelly 
МасТшог Editorial Board 
MacTutor Vol. 4 No. 7 


BASIC 


Тиле 


| | True BASIC™ 
True Basic Plays the Simon Game 


é file Edit Custom Run Windaws Help 


| 


Fig. 1 Our Simon Game in True Basic 
(This is in color on the Mac Ii!) 


available from MacTutor' s Mail Order Store at the back of this 
issue. -Ed] 
Color Palette Manipulation 

True Basic allows you to change colors in the color palette. 
The SET COLOR МІХ (x) r,g,b statement sets the color x to the 
color specified by the red, green, blue values given by r,g and b. 
In True Basic the values of r,g and b are from 0 to 1 (whereas the 
hardware is looking for values from O to 65535). For the user it 
is much easier to think in terms of 0 to 1 than 0 to 65535. A SET 
COLOR MIX (5) .25,0,0 would change color 5 to 25% of the full 
red value and no green and blue. The number of distinct 
intensities available on your Mac II depends on the number of 
colors available. You may use ASK MAX COLOR to determine 
how many of the colors are available out of the total 256 colors 
(assuming you can display 256 colors). Actually ASK MAX 
COLOR returns n-3 colors because some of the colors are already 
in use by the system. ASK MAX COLOR will only let you know 
the maximum possible number of colors. SET COLOR MIX is 
ignored on black and white systems. 

Using color is fun as you can see from this months program 
(see the black and white figure 1; on the Mac II, this Simon game 
is in color with the background an animated palette). The theme 
I selected is based on the Simon game (Milton Bradley) which 
I'm sure you have all seen before. There are a few things which 
must be done to set up the program if you are starting from 
scratch. First go to a paint program (color is preferred, but not 
necessary) and create the main PICT for the game as shown here 
in figure 2. 
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Fig. 2 PICT for the Simon Game 


It doesn’t matter what colors are used or even the shape of the 
colored areas. The program will do a fill (FLOOD x,y statement 
in True Basic) and fill in the correct colors as long as the size of 
the PICT rectangle remains the same size. If the same color is 
used as the original, the SET COLOR MIX statement needs to 
use a different color because the FLOOD statement fills the area 
till it finds a change in color or it finds the same color as the one 
being use to fill the area. 

Next the PICT should be stored in the clipboard and then run 
the 'Save Clip' program. The purpose of this program is to 
convert the clipboard PICT file into a disk PICT file. True Basic 
could read the PICT file direct, but this way we know that we have 
only selected the actually PICT and not some of the areas 
surrounding it. When the 'Save Clip' program asks for a 
filename, the name of the file as used in the main program should 
be used (in this case ‘Prof Says.PICT' is the filename). 


! Save Clip 
! This program will save the contents of the clipboard to a 
file 
LIBRARY *Mactools*^ 
LIBRARY "PictLib*^ 
DECLARE DEF MacPutFile$ 
LET donef lag-0 
DO until doneflags1 
CALL Read_cl ipboard( “PICT”, s$) 
LET fi lename$=MacPutF i 1le$(50,58, “Enter Filename to save 
as. ыы ыыр: 
IF f ilename$«» "^" THEN 
CALL Write.pictfileCfilename$,s$) 
PRINT “Do әпоіһег?”; 
GET KEY Answer 
IF Answer € ord(^Y^) OR Answer O ordC^y^) THEN LET 
допе!1ад= 1 
ELSE 
LET donef lag=1 
END IF 
LOOP 
END 


The main program requires the use of the MacTools and 
PictLib Libraries. These are provided with the True Basic 
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package. To help True Basic find the libraries (in case they are 
moved to a strange place) the ALIAS statement should be used. 
The manual is not too clear on this, but ALIAS statements should 
be run from a file “TB Startup’ automatically when True Basic is 
run. This is a satisfactory solution to fix the HFS problems that 
True Basic 1.0 had. 

The next thing that might be different for you is the way that 
True Basic specifies the window (or screen) coordinates. No 
matter what kind of computer True Basic is being run on, the 
coordinates are the same. The coordinates start with 0,0 in the 
bottom left corner of the screen and go to 1,1 in the top right 
corner. Then using the SET WINDOW statement any coordinate 
system may be mapped to the current window. A smaller portion 
of the screen may be partitioned off to act as a kind of clipping 
region for text. The PictStuff library seems to only use screen 
coordinates and doesn’t pay much attention to the location of the 
window. However, by using the CALL Set_Frame statement, the 
PICT graphics may be displayed anywhere you want. The OPEN 
#1:screen left, right, bottom, top statementis set up for the Apple 
RGB Monitor. These values may have to be adjusted if used on 
other size monitors. 

Of course, True Basic statements are used all the way 
through the program except for the MacTools calls which are 
used mostly used to display text. A few of the other Macintosh 
things which are included in the MacTools Library are: 


MacPenSize(width, height) 

MacPenMode( mode ) 

MaecTextFontCfont) 

MacTextFace(style$) 

MacTextMode (mode ) 

MacTextSize(size) 
MacTextBoxCleft,right,bottom, top,s$, just$) 
MacSpaceExtreCextra) 


MacGetFontInfoCascent, descent, widmax, leading) 
MacGetFile$Ch,v, type$, but ton$) 

MacPutF i le$Ch,v,pr$, iname$, but ton$) 
MacSysBeep(duration) | 

also other commands for drawing ovals and rectangles. 


I am somewhat disappointed that more of the Macintosh 
Toolbox is not included (built in) to the True Basic system. Of 
course the Developer Toolkit should include the rest of the 
Macintosh ROM world, but it would be nice to have it integrated. 
[We are still waiting for delivery of the Developer Toolkit. True 
Basic is sending return postcards to order the library but as yet 
we have not seen it. -Ed] If youuseany library alot, you may load 
it when you startup and have it resident in memory so at least 
there is a way to simplify the system. I hope to be able to review 
the Developer Toolkit when it is released. I will have more to say 
about True Basic next month. 


! Professor Mac Says. 

! By David Kelly 

| @MacTutor, 1988 

! With special thanks to Milton Bradley Co. 
! For their "Simon^ Game 


LIBRARY *Mactools*^ 


! MacStuff Library 
LIBRARY "PictLib*^ 


! PICTStuff Library 
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DECLARE DEF MacGetFile$ 
DIM notes(31) 


RANDOMIZE 

LET skilllevel=8 ! Set up levels 

LET level=1 

SET BACKGROUND COLOR 10 ! Get a Background color 


OPEN 81:өсгееп .25,.67,.165,.75! open a section of screen 
WINDOW 81 ! and use it as а window 

SET WINDOW 9, 1,0, 1 

ASK SCREEN 8,b,c,d 

CALL set fremeCa,b,c,d) 


LET filename$="Prof Says.PICT^ ! Get the PICT resource 
IF filename$«»*^ THEN 
CALL Read.pictf ileCf ilename$,s$) 
CALL Draw_string(s$, 1) 
ELSE 
PRINT “Prof Says.PICT file not found!” 
END IF 


! Set up the main screen 
CALL SetRed 


FLOOD .3,.7 | Fill the shape with Red 
CALL SetBlue 

FLOOD .7,.7 | Fill the shape with Blue 
CALL SetGreen 

FLOOD .3,.3 ! Fill the shape with Green 
CALL SetYellow 

FLOOD .7,.3 ! Fill the shape with Yellow 


! Turn off all shapes 

CALL derkred 

CALL darkblue 

CALL darkgreen 

CALL darkyel low 

ASK WINDOW a,b,c,d 

BOX KEEP a,b,c,d in None$ ! Save PICT so it can be 
! restored later 

CALL MacTextFont(2) ! Get New York font 

SET TEXT JUSTIFY “center”, “half” 

00 ! Start the Main program loop 


SET COLOR MIX (0) rnd,rnd,rnd ! change background color 


CALL SetButtonsClevel) 
DO 
LET Animat ioncount=Animationcountt 1 
IF Animationcount?25090 then 
SET COLOR MIX (0) rnd,rnd,rnd ! change the 
background color 
LET Animationcount-0 
END IF 
GET MOUSE х,у,5 
IF өзг! then 
GET POINT x,y! Get the mouse press 
LET result=0 


! Check for mouse press 


CALL PtInRect(x,y, .12,.295,.7,.8,result)! Level 


IF result=1 then 

(ЕТ skilllevel=8 

LET level=1 

CALL SetStartGameBut ton(Level ) 
END IF 
LET result- 


CALL PtInRect(x,y, .32, .495, .7, .8,result)! Level 


IF result=1 then 
LET skilllevel=14 
LET level=2 
CALL SetStar tGameBut ton(Level ) 
END IF 
(ЕТ result-9 
CALL PtInRect(x,y, .505, .680, .7, .8,result) 
| Level 3 
IF result=1 then 
(ЕТ skilllevel=20 
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! Level 4 


notesC)) 


LET level=3 
CALL SetStartGameButtonCLevel) 
END IF 
LET result=8 
CALL PtInRect(x,y, . 705, .880, .7, .8,result) 


IF result=1 then 
LET skilllevel=31 
LET level=4 
CALL SetStar tGameButton(Level ) 
END IF 
(ЕТ results 
CALL PtInRect(x,y, .3,.7,.05, . 15,result) 
IF result=1 then 
| Quit Routine 
SET COLOR “White” 
BOX AREA 0, 1,9, 1 
SET COLOR “Black” 
BOX LINES @, 1,9, 1 
SET COLOR “Blue” 
CALL MacTextSize(24) 
PLOT TEXT, AT .5,.6:*Thank you for” 
PLOT TEXT, AT .5,.4:"Reading MacTutor™” 
STOP 
END IF 
(ЕТ resul {=6 
CALL PtInRect(x,y, .3, .7,.2, .3,result) 
IF result=1 then 
! Plag the Game 
BOX SHOW none$ at 0,0 
LET x=0 
LET у-0 
LET numberofnotes-1 
LET tempo- 100 
DO until numberofnotes=skilllevel 


CALL PlaySequence(numberofnotes, tempo, 


FOR i=1 to numberofnotes 
SET COLOR MIX (0) rnd,rnd,rnd 
GET POINT х,у 
CALL buttonpress(x,y,selection) 
IF selectionOnotesCi) then 
CALL MacSysBeep(500) 
CALL MacSysBeep(590) 
CALL MacSysBeep(590) 
EXIT DO 
END IF 
NEXT i | ] 
LET numberofnotes-numberofnotes* 1 
LET tempo=tempoti* 10 


PAUSE 1 
LOOP 
CALL SetButtons( level) 
END IF 
IF 


SUB SetButtons(GameLevel) ! Set Game Buttons 
CALL MacTextSize( 14) 
SET COLOR “white” 


BOX AREA 
BOX AREA 
BOX AREA 
BOX AREA 
BOX AREA 


505, .680, .7, .8 
.705, .880,.7,.8 


Level 3 Button 
Level 4 Button 


‚3,‚.1,.05,.15 ! Quit Game Button 
.12,.295,.7,.8 ! Level 1 Button 
.32,.495,.Т,.8 ! Level 2 Button 

! 

! 


SET COLOR “Black” 


BOX LINES .3,.7,.05,.15 

BOX LINES .12,.295,.7,.8 
BOX LINES .32,.495,.7,.8 
BOX LINES .505,.680,.7,.8 
BOX LINES .705,.880,.7,.8 


Quit Game Button 
Level 1 Button 
Level 2 Button 
Level 3 Button 
Level 4 Button 
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SET COLOR “Red” 
CALL SetStartGameButtonCGameLevel) 
PLOT TEXT, AT .5,.11:^Quit Game” 
CALL MacTextSizeC 12) 
PLOT TEXT, AT .105,.77:71" 
PLOT TEXT, AT .4,.77:%2" 
PLOT TEXT, AT .575, . 7T: ^3" 
PLOT TEXT, AT .825,. 77: "4" 
END SUB 


SUB SetStartGameButtonCGameLevel)  ! Set up the Start Game 
Button 

SET COLOR MIX (Ø) rnd,rnd,rnd 

CALL MacTextS izeC 14) 

SET COLOR “White” 

BOX AREA .1,.9,.2,.3 ! Start Game Button 

SET COLOR “Black” 

BOX LINES .1,.9,.2,.3 ! Start Game Button 

SET COLOR “Red” 

PLOT TEXT, AT .5,.26:"Start Game Level ” & STR$CGamelevel) 
END SUB 


SUB SetNone ! Display the PICT with colors off 
BOX SHOW None$ at 0,0 

END SUB 

SUB SetRed 


SET COLOR MIX (13) 1,0,0 
SET COLOR 13 

END SUB 

SUB DarkRed 
SET COLOR MIX (13) 0,0,0 
SET COLOR 13 

END SUB 

SUB SetGreen 
SET COLOR MIX (142 0,1,0 
SET COLOR 14 

END SUB 


SUB DarkGreen 
SET COLOR MIX (14) 0,0,0 
SET COLOR 14 

END SUB 

SUB SetBlue 
SET COLOR MIX (15) 0,0,1 
SET COLOR 15 

END SUB 

SUB DarkBlue 
SET COLOR MIX (15) 0,0,0 
SET COLOR 15 

END SUB 

SUB SetYellow 
SET COLOR MIX (16) .9,1,0 
SET COLOR 16 

END SUB 

SUB DarkYellow 
SET COLOR MIX (16) 0,0,0 
SET COLOR 16 

END SUB 

SUB FlashRed 
SET COLOR MIX (13) 1,0,0 
LET note$-^o5 mf ms c" 
PLAY note$ 
PAUSE .5 
SET COLOR MIX (13) 0,0,0 

END SUB 

SUB FlashGreen 

x SET COLOR MIX (14) 0,1,0 
LET note$="05 mf ms a” 
PLAY note$ 
PAUSE .5 
SET COLOR MIX (14) 0,0,0 

END SUB 
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SUB FlashBlue 
SET COLOR MIX (15) 0,0,1 
LET note$="05 mf ms >a” 
PLAY note$ 
PAUSE .5 
SET COLOR MIX (15) 0,0,0 
END SUB 
SUB FlashYel low 
SET COLOR MIX (16) 1,1,0 
LET note$-^o5 mf ms е” 
PLAY note$ 
PAUSE .5 
SET COLOR MIX (16) 0,0,0 
END SUB 
SUB PtInRect(x,y, left,right, bottom, top, Result) 
| See if point is in Rectangle 
IF x» left and x«right and y»bottom and y<top then 
(ЕТ Result=1 
ELSE 
(ЕТ Result-0 
END IF 
END SUB 


SUB Buttonpress(x,y,selection) ! Handle button press 
CALL PtInRect(x,y,8, .5, .5, 1,result) 
IF result=1 then LET selectedcolor=13 
CALL PtInRect(x,y,8, .5,0, .5,result) 
IF result=1 then LET selectedcolor= 14 
CALL PtInRect(x,y, .5, 1, .5, 1,result) 
IF result=1 then LET selectedcolors 15 
CALL PtInRect(x,y, .5, 1,8, .5,result) 
IF result=1 then LET selectedcolor= 16 
SELECT CASE selectedcolor 
CASE 13 

CALL f lashred 

LET selection=1 
CASE 14 

CALL f lashgreen 

LET selection=2 
CASE 15 

CALL f lashblue 

LET selection=3 
CASE 16 

CALL flashyel low 

LET selection=4 
CASE ELSE 

LET selection=0 
END SELECT 

END SUB 


SUB PlaySequence(numberofnotes, tempo,notes()) ! Play the notes 
LET tempo$-"t"&str$Ctempo) 
PLAY tempo$ 
FOR іс! to numberofnotes 
SET COLOR MIX (0) rnd,rnd,rnd 
IF notesCi)-0 then 
LET notezintC4*rnd2*1 


ELSE 
LET notesnotes(Ci) 
END IF 
SELECT CASE note 
CASE 1 
CALL flashred 
CASE 2 


CALL flashgreen 
CASE 3 
CALL flashblue 
4 


CASE 
CALL flashyellow 
END SELECT 
LET notes(i)=note = 
NEXT i | 
END SUB м, 


Basic School 


True Basic & Prototyper Reviewed 


True Basic 2.01 Run Time Package 


I promised you some more information about the new 
version of True Basic (2.01). The good news is that you can now 
create double-clickable applications with the runtime package 
that is included with the price of True Basic ($99.95 retail). This 
price includes both a commercial and non-commercial 
license.There is no longer an extra charge for the license for 
"unlimited commercial" use. The Bad news is that the Devel- 
oper's Toolkit is not included with the True Basic interpreter yet. 
UGH! According to True Basic it will be available soon. The 
Developer's Toolkit includes all the ROM routines for creating 
the Macintosh User features we all know and love. As much as 
I would like the Toolkit to be included with True Basic, they have 
come along way. After all, last time I reviewed this the runtime 
package was priced way out of sight and even the interpreter was 
overpriced. 

Youare probably wondering about the runtime package and 
just what it is. I just received a copy of the runtime package 
yesterday, but I can pass onto you some information about it. The 
runtime includes two new libraries of routines, named Bundle 
and Launch*. Bundle is a “compiled” True Basic program which 
sets up the signature id of your application. Launch* consists of 
some routines for getting your application's name and getting the 
names of files to be opened or printed by the application that were 
selected in the finder when the application was run. Two 
application files are included in the runtime package too. RTP is 
anapplication shell program which is that base of all applications 
that you will create. RTP contains the ENTIRE True Basic 
interpreter and is used as the shell which will ‘гип’ your program 
after itis attached. The other application is named Binder and is 
used to combined compiled True Basic programs with the RTP 
application so that they can now be considered one application. 
The RTP application (the interpreter) consists of 73K of True 
Basic standard packages so you should be aware that your 
programs will always be at least 73K in size. That may be bad 
news, but at least the application can be created. 

True Basic has one of the most extensive sets of library 
routines available for any language. Some of these routines are 
very valuable for scientific/engineering applications. True Basic 
Inc. says that all the original versions of the libraries work with 
True Basic 2.01 except for the Developer's Toolkit and the 
Communications Support package. Both of these have been 
updated to work with version 2.01. The Developer's Toolkit, as 
I mentioned before, contains all the latest Macintosh ROM 
routine calls. Some of the libraries available include: Business 
Graphics Toolkit, Scientific Graphics Toolkit, 3D Graphics, 
Communications Support, Forms Management, Sorting and 
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Searching, Advanced String Library, and Mathematician's 
Toolkit. All of these are list price of $69.95 each. They аге 
probably worth itif you think you need the function they perform. 

To give you a little feel for the runtime package I have 
included the following short program which makes use of the 
launch* library. The program displays the files which were 
selected in the finder launch of the application. 


! Runtime Demo 


LIBRARY *launch*^ 

CALL AppParms(name$, message , nf iles) 

PRINT “Current Application name is:”;name$ 
SELECT CASE message 

CASE 0 


PRINT “Files to be opened:” 
CASE 1 
PRINT “Files to be printed:^ 
END SELECT 
FOR i21 to nfiles 
CALL AppfileCi,f ilename$, ^^) 
PRINT filename$ 
CALL ClrAppFileCi) 
NEXT i 
if nfiles=0 then print “NONE” 
GET KEY k 
END 


SAMPLE OUTPUT: 


Current Rpplication name is:TB Runtime Оево 
Files to be printed: 

Hard Disk II:Basic:True Basic 2.0:TB Startup 
Hard Disk II:Basic:True Basic 2.0:Runtime.deao 
Hard Disk II:Basic:True Basic 2.0:Runtime.denmo* 


So just what's so great about True Basic? Actually, the main 
drawback in the previous version was its inability to be a double- 
clickable application. As a language, itis excellent, especially in 
support of scientific applications. On the positive side, True 
Basic has the strongest version of Basic available on the Mac. 
The reason I say it is the strongest because the structure and 
functional capabilities of the language are solid and reliable (I 
haven't seen any system bombs!) The library routines are very 
extensive, more extensive than any for MS Basic. Recursion is 
supported. The 68881 math coprocessor is supported. Color is 
supported with ability to modify color palettes (July, 1988 
MacTutor). Since the runtime package is now made more freely 
available, you can use True Basic more effectively in real world 
applications (instead of the class room world that you have 
without the runtime package). 


No Developer's Toolkit Yet 
On the negative side, there are a few areas that could have 
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been cleaned up а bit. The first negative, and my strongest point 
is that the Developer's Toolkit is not included with the inter- 
preter. Since I’ve already mentioned this before I won't dwell on 
it, but I feel it is a *must һауе” if you are doing any serious 
development. Next there are a few compatibility/ user interface 
issues some of which you can fix yourself. One problem is the 
small size of the Standard GetFile/SaveFile Dialog windows. 
This сап be fix with a little ResEdit work. The problem is that the 
window is only wide enough for short file names (like version 1.0 
was when Mac 128K came out). Fortunately this is fixable. 

While it is true that True Basic will run with Multifinder, 
True Basic does not know when to update windows when they 
have been overwritten by other applications or desk accessories 
and without the Developer's Toolkit it would be impossible to 
know that a window needs to be refreshed. True Basic was 
designed to run in one window which happens to be the size of 
the screen (any size screen). All graphics commands are auto- 
matically scaled to work with whatever size screen (on whatever 
computer True Basic runs on). Since the main True Basic 
window is the size of the screen and is not adjustable, it will 
overlap ALL windows and icons which are running in the 
background with Multifinder. Since the menus are disabled 
during True Basic runtime (runtime package), the only way to 
switch applications is by clicking on the icon in the upper right 
corner (in the menu bar). The are a few refinements that could be 
done here to make it more Multifinder compatible. 

True Basic for the Macintosh comes with two manuals, the 
Reference Manual, and the Macintosh™ User's Guide. The 
Reference Manual is much improved over the old version in- 
cluded with version 1.0. The True Basic statements are listed 
alphabetically in the back half of the book (part III), but since 
there are sometimes several statements on a page you have to read 
carefully to find what you are looking for. The Macintosh? 
User's Manual is just what it says it is, a user's manual. The first 
half of the book tells what each menu of the True Basic applica- 
tion does, then there are some sections telling about a few 
Macintosh only routines which are included. Included in this is 
sections on color support, standard GetFile/PutFile stuff, and a 
few graphics commands for fonts and basic graphics (about like 
the original MS Basic Toolbox of Graphics commands). The rest 
of the graphic support (99% of it) is built into the standard True 
Basic. 

Should you buy it? Well, if you do I recommend that you be 
sure to get the Developer's Toolkit too. I haven't seen the 
Developer's Toolkit yet (I hope to be able to review it soon!) so 
I can't form an opinion yet, but since I expect it to be similar or 
better than the original ToolBox routines (from version 1.0) I 
would say that it should turn out to be a pretty decent package. 
True Basic costs $99.95, so with the Toolkit it will be about $170 
for the whole enchilada. If you are an educator you may be able 
_togetreally good prices on everything (about half price). I would 
say that there is a lot of potential for more support for True Basic 
in the future. 


ProtoTyper Creates Shell Program Code 
Thank goodness for software developers. At least that's 
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what I say when I don't have the time to write my own software 
and I need to do something right now. The problem is the length 
of time it takes to develop software. There are a number of you 
that, like myself, work full time at a job other than programming 
and then have family and other responsibilities take you away 
from that great idea for a software package. Time is valuable, 
especially when the only time you may have is on weekends and 
a little time each evening. 

One solution to my time schedule problem has been to write 
most of my programs in Basic because it is “quick and dirty". I 
can usually see my results during the same weekend or maybe 
two weekends for a longer program, compared to several weeks 
working with a full blown Pascal program. That used to be the 
only solution available to me (except to give it up and not write 
anything) until recently. It's been different lately. 


PRESENTING... PROTOTY PER™ 


Back at MacWorld Expo in San Francisco I saw Proto- 
typer™ for the first time. Prototyper is one of those truly 
ingenious ideas whose time has come. If you haven’t yet seen it 
or read about it yet then keep on reading. If you have heard of 
Prototyper then I don’t want it said that it wasn’t ever mentioned 
in MacTutor. 

What is Prototyper? Prototyper is a tool which is used to 
help you to develop the conceptual design of your software and 


Prototyper Sample 


About Dialog 
sample Window 


get you started with your software. Itis notall things toall people, 
but it is a unique tool which may be used to save many hours of 
development time. Prototyper is not a language compiler; it is a 
code generation program and resource compiler of a sort. Any- 
one that uses resources such as menus, windows, dialogs, icons, 
or controls can make use of Prototyper. 

Prototyper is not just another substitute for ResEdit. ResEdit 
is still very useful for what it does, but Prototyper adds another 
element of user friendliness to the sometimes hostile world of 
software development. Let’s look at a typical sample Prototyper 
application. The Prototyper window lists the windows and 
dialogs that have been defined. Clicking on the menu icon 
invokes the menu editor. Clicking on the window icon invokes 
the window/dialog editor. (See fig. 1 previous page) | 

The Menu editor is similar to other menu editors I have seen 
before. By clicking in the first column, Menus:, you can select 
and change the menu to edit. Clicking on an item in the second 
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column lets you edit each item. The current menu is presented in 
the menu bar so you can see what you actually get. It's a good 
thing because the scrolling window is so narrow that longer menu 
item names can't be seen. А wider window here or a better way 
to scroll would be valuable, but is not essential to creating a menu 
successfully. You may check, disable items, or add command- 
keys. Icons may be added to menus to add a personal touch. Icons 
may be read in from any application and modified with the icon 
editor. The Link button links any item to a defined window or 
dialog. More on that later. Only one menu can be created. (See 
fig. 2 below) 

The window editor allows you to create almost any kind of 
window, dialog, or alert and add text, buttons, scroll bars, active 
or inactive icons, lists, lines, and rectangles. You should decide 
before hand whether or not you should use a window, dialog or 
alert as defined in the guidelines in Inside Macintosh. At least 
once I created a dialog or alert and used it the wrong way and 
Prototyper bombed! Except for that it was extremely easy to use. 
(See fig. 3 below) 

I created a sample window and sample dialog for this 
example. The dialog will serve as my About Dialog when the 


Menu Editor Wa ss 


К О Disabled 
| O Checked 


| Ож кеу: (| 


i 
i C Menu Icon 


Я (tink) 


application is created so I have linked the About menu item (in 
the Menu Editor) to the DIALOG -About Dialog window and set 
the OK button to close the dialog when pressed. I included some 
sample buttons and a scroll bar so that you could see how that 
works. The scroll bars and buttons will move and toggle, but 
don't effect anything else. They won't do anything until they are 
updated in the Pascal source code. (See fig. 4 below) 

There are a few areas that are deficient that SmethersBarnes 


BE WINDOW - Sample Window Seen 


dit Text 


A Checkbon! > МесТиісгі 


О Сһескһон2 


О Radio! @ Radio2 
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needs to work on to improve the next version. One deficiency is 
that you can’t set up hierarchical menus from within Prototyper. 
That doesn’t mean that youcan’t do it yourself. It just means that 
you won’t have the menu resources for hierarchical menus set up 
for you. The next version of Prototyper promises hierarchical 
menus and support for C. The current version supports four 
different versions of Pascal, LightSpeed™ Turbo™, MPW™, 
and TML™. I don't know if that includes the new TML Pascal 
II which runs under MPW. I'm very pleased with the results of 


DIRLOG - Rbout Dialog 


Sorry, this program really does nothing. 
©1988 MacTutor 

91986 THINK Technologies, Inc. Certain 
portions of this software are copyrighted 
by THINK Technologies, Inc. 
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the LightSpeed code. You set up your preferences and dump the 
code to the appropriate LightSpeed type files. A resource file is 
also created along with an RMaker source file (except for PICT 
resources). (See fig. 5) 

Prototyper generates a shell for you which incorporates all 
of the menus and windows which were created in the Menu and 
Window Editor. It's too bad thatonly one menu may be used, but 
the shell must be able to work with many different application 
designs. A sample of the LightSpeed Pascal is given on the source 
code disk for this issue of MacTutor. 

I wholeheartedly recommend Prototyper to anyone that 
would like to write full blown applications, but can't use Basic 
for one reason or another and doesn't want to take a lot of time 
writing the shell the application. Some of you might not need 


Preferences 
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Print Formats: Code Type: 
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Prototyper if you already have your own custom application 
shell, but even then Prototyper is a great way to create the 
resources. There are things that can and will improve, such as 
adding hierarchical menus and generation of C source code, but 
even without some of the enhancements, Prototyper is a major 
time saver. Improvements will come with time. 


unit About Dialog; 


(File name:About.Dialog.Pas ) 
(Function: Handle a dialog ) 
(History: 6/13/88 Original by Prototyper. ) 


interface 
procedure 0. About. Dialog; 
implementation 


const (item numbers for controls in the Dialog) 


I_Static_Text = 2; 
var 
ExitDialog : boolean; (Flag used to exit the Dialog) 
procedure D. About. Dialog; 
var 
GetSelection : DialogPtr; (Name of dialog) 
(*ExitDialog : Boolean; declared global for filter 
routine *) (Flag to exit dialog) 
tempRect : Rect; 
ОТуре : Integer; 
Index : Integer; 
DItem : Handle; 
CItem, CTempItem 
sTemp : Str255; (temp holding) 
itemHit : Integer; (Get selection) 
temp : Integer; (temp holding) 
Icon.Handle : Handle; (Temp handle to read Icon ) 
NewMouse : Point; (Mouse loc,tracking Icon presses) 
InIcon : boolean; (Flag to say pressed in en Icon) 
ThisEditText : TEHendle; (Handle to Dialogs TE record) 
TheDialogPtr : DialogPeek; (Pntr to Dialogs def record) 


(Temporary tectangle) 

(Type of dialog item) 

(For looping) 

(Handle to the dialog item) 
: controlhandle; 


(This is ап update routine for non-controls in the dialog) 
(This is executed after the dialog is uncovered by an alert) 
procedure Refresh.Dialog; (Refresh dialogs non-controls) 
var 
rTempRect :Rect; 


(Temp rectangle used for drawing) 
begin 


begin (Start of dialog handler) 
GetSelection := GetNewDialog(2, nil, 
ShowW indowCGetSelection); 
SelectWindow(GetSelection); 
SetPort(GetSelection); 
TheDialogPtr := DialogPeek(GetSelection); 
ThisEditText := TheDialogPtr^.textH; 
HLockCHandleCThisEditText2); (Lock it for safety) 
ThisEditText^^.txSize :- 12; (TE Point size) 
Техі5іге( 12); (Window Point size) 
ThisEditText^^.txFont := systemFont; (TE Font ID) 
TextFontCsystemFont); (Window Font ID) 
ThisEditText^^.txFont := 0; (TE Font ID) 
ThisEditText^^.fontAscent := 12; (Font ascent) 
ThisEditText^^.lineHeight := 12 * 3 * 1; 

(Font ascent + descent + leading) 

HUnLock(Handle(ThisEditText)); ^ (UnLock handle) 


Pointer(-1) ); 
(Open a dialog box) 
(Lets see it} 


(Setup initial conditions) 
ExitDialog:=FALSE; (Do not exit dialog handle loop yet) 
repeat (Start of dialog handle loop) 
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ModalDialog(nil, itemHit); (Wait til item hit} 
GetDItem(GetSelection, itemHit, ОТуре, DItem, tem- 
pRect); (Get item information) 

CItem := Pointer(DItem); (Get the control handle) 

if CItemHit =I1_0K) then (Handle Button pressed) 
begin 
(?? Code to handle this button goes here) 
ExitDialog:=TRUE; (Exit dialog when selection made) 
end; (End for this item selected) 

until ExitDialog; 


(Get results after dialog) 
DisposDialog(GetSelection); (Flush dialog) 
end; (End of procedure} 
end. (End of unit) 


unit HandleTheMenus; 


(File name :HandleTheMenus .Раз} 
(Function: Handle all menu selections.) 

This procedure is called when а menu item is selected.) 
( There is one CASE statement for all Lists. There is) 
( another CASE for all the commands in each List.) 
(History: 6/13/88 Original by Prototyper. 


interface 


uses 
About.Dialog, Sample Window, InitTheMenus; 


procedure Handle.My.MenuCvar doneFlag:boolean; 
theMenu, (һе еп: integer; var theInput:TEHandle); 


implementation 


procedure Handle_My_Menu; (menu selections realtime) 
const 
L_Apple = 201; 
C_About_this_Sample = 1; 


2 


(Menu list) 


L_File = 202; (Menu list) 
C-Quit = 1; 
LEdit = 203; (Menu list) 
C-Undo = 1; 
С-Си{ = 3; 
С-Сору = 4; 
C-Peste = 5; 
C_Clear = 6; 
C-Select. A11 = 7; 
ver 


DNA: integer; 
BoolHolder :boolean; 
DAName :Str255; 
SavePort:GrafPtr; 
begin 
case theMenu of 
L_Apple: 
begin 
case theItem of (Handle commands in menu list) 
C_About_this_Sample: 
begin 
D_About_Dialog; (Call dialog for this) 
end; 
otherwise 


(For opening DAs} 
(For SystemEdit result) 
(For getting DA name} 
(Save current port when opening DAs) 
(Start of procedure} 
(Do selected menu list) 


(Handle the DAs) 
begin (Start of Otherwise) 
GetPort(SavePort); (Save current port} 
GetItemCAppleMenu, theItem, ОАМате); (DA) 
ОМА := OpenDeskAcc(DAName); (Open DA ) 
SetPort(SavePort); {Restore saved port} 
end; {End of Otherwise} 
end; (End of item case) 
end; (End for this list) 


L.File: 
begin 
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case theltem of 
C_Quit: 
begin 
doneF lag := TRUE; 
end; 
otherwise 
begin 
end; 


end; (End of item case} 
end; (End for this list) 


L Fdit: 
begin 
BoolHolder := SystemEdit ( theltem - 1); 
(Do DA editing) 
if not (BoolHolder) then 
(If not & DA then we get it) 
begin (Handle by using а Cese statment) 
case theltem of (Handle all commands іп list) 
C-Undo: 
begin 
22 ADD IN WHAT THIS COMMAND SHOULD 00) 
end; 
С Cut: 
begin 
?? ADD IN WHAT THIS COMMAND SHOULD DO) 
end; 
C Copy: 
begin 
?? ADD IN WHAT THIS COMMAND SHOULD DO) 
end; 
C-Peste: 
begin 
?? ADD IN WHAT THIS COMMAND SHOULD 00) 
end; 
C_Clear: 
begin 
22 ADD IN WHAT THIS COMMAND SHOULD 00) 
end; 
C_Select_All: 
begin 
2? ADD IN WHAT THIS COMMAND SHOULD DO) 
end; 
otherwise (Send to a DA) 
begin (Start of the Othersize) 
end; (End of Otherwise) 


end; (End of item case) 
end; (End of not BoolHolder) 
end; (End for this list) 
otherwise 
egin 
end; 
end; (End for lists) 
HiliteMenu(@); (Turn menu selection off) 
end; (End of procedure Handle_Mu Menu) 
end. (End of unit) 


unit InitTheMenus; 


(File name: InitTheMenus .Раѕ) 

(Function: Pull in menu lists from a resource file.) 

( This procedure is called once at program start.) 

( Арр1еМепи is the handle to the Apple menu, it is also) 
used in the procedure that handles menu events.) 

( History: 6/13/88 Original by Prototyper. 


interface 
procedure Init My Menus; (Initialize the menus) 


var 
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AppleMenu:MenuHandle; (Used to handle DAs} 


implementation 
procedure Init. My Menus; (Initialize the menus) 
const 
Menul = 201; (Menu resource 10) 
Menu2 = 202; (Menu resource 10) 
Menu3 = 203; (Menu resource 10) 
var 


tempMenu:MenuHandle; (Throw away all other menu handles) 
begin (Start of Init_My_Menus) 
ClearMenuBar ; (Clear any old menu bars) 
( APPLE menu, used for About & desk accessories.) 
tempMenu := GetMenu(Menu1); (Get menu from res f ile) 
AddResMenuCtempMenu, ‘DRVR’); (Add іп DAs} 
InsertMenu CtempMenu, 0); (Insert menu into menu bar) 
App leMenu :=tempMenu; (Save menu handle for later} 
( This menu is File } 
tempMenu := GetMenu(Menu2); 
InsertMenu CtempMenu, 0); 
( This menu is Edit 
tempMenu := GetMenu(Menu3); 
InsertMenu CtempMenu, 2); 
DrewMenuBer ; (Draw the menu ber) 
end; (End of procedure Init. My Menus) 
end. 


Set RUN OPTIONS to use the resource file 
Prototyper_Samp le .RSRC 

RMaker file to use is Prototyper_Sample.R 

The Project should have the following files in it: 


MacPasL ib LSP This is the Pascal library file 

MacTraps LSP This is for Mac routines to be called} 

ROM85 LSP This is necessary if you use any 
Lists) 

ROM85L ib LSP This is necessary if you use апу 
Lists) 

ListManager LSP This is necessary if you use anu 
Lists) 

About_Dialog Modal Dialog 


Sample. Window 
InitTheMenus .Pas This initielizes the Menus. 
HendleTheMenus Hendle the menu selections. 
Prototyper_Sample.Pas ` Main program 


Window 


Program Prototyper_Sample; 

(Program name:Prototyper_Sample.Pas  ) 

(Function: This is the main module Гог this program. ) 
(History: 6/13/88 Original by Prototyper. 


uses 
About_Dialog, Semple Window, InitTheMenus, HendleTheMenus; 


var (Main veriables) 
myEvent :EventRecord; (Event record for all events) 
doneF 1ag:boolean; (Exit program flag) 
code: integer; (Determine event type) 
whichWindow:WindowPtr; (See which window for event) 
tempRect :Rect; (Rect for dregging) 
mResult:longint; | (Menu list and item selected values) 
theMenu, theI tem: integer; (Menu list and item selected) 
chCode : integer; (Key code} 


ch : char; (Key pressed in Ascii) 

theInput : TEHandle; (Used in text edit selections) 
begin (Start of main body) 

MoreMasters; (This reserves space for more handles) 

Init6raf CéthePort); (Quickdraw Init) 

InitFonts; (Font manager init) 
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InitWindows; (Window manager init) 


InitMenus; (Menu manager init) 
TEInit; (Text edit init) 
InitDialogs(nil); (Dialog manager) 
FlushEvents(everyEvent, 0); (Clear out all events) 
InitCursor; (Маке әп arrow cursor) 


doneF lag: «FALSE; (Do not exit program yet) 

Ini t. My. Menus; (Initialize menu bar) 
theInput:=nil; (Init to no text edit selection active) 
Init Sample Window; {Initialize the window routines) 
Open_SampleWindow; (Open wind routines at program start) 


repeat (Start of main event loop) 
if CtheInput © nil) then (See if а TE is active) 
TEIdleCtheInput?); (Blink cursor if everything ok) 
SystemTask; (support of desk accessories) 
if GetNextEventCeveryEvent, myEvent) then 
begin (Start handling the event) 
code := FindWindow(myEvent.where, whichWindow); 
case myEvent .what of (Decide type of event) 
MouseDown : (Mouse button pressed) 
begin (Handle the pressed button) 
if (code = inMenuBar) then 
begin (Get menu selection and handle it) 


mResult := MenuSelect(myEvent . Where); 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 


Handle_My_Menu(doneF lag, theMenu, the! tem, 
theInput); 


end; (End of inMenuBar) 


if (code = InDrag) then (window drag area) 
begin (Do dragging the window) 
tempRect:= screenbits.bounds; (screen 1,t,r,b) 
SetRect(tempRect, tempRect .Lef t* 10, 
tempRect . Top*25, tempRect .Right- 10, tempRect .Bottom- 10); 
DragWindow(whichWindow, myEvent.where, 
tempRect); 
end; (End of InDrag) 


if (code = inGrow) then (Іп grow area) 
begin (Handle the growing) 
tempRect:= whichWindow^.portRect; 
(Get size and position) 

tempRect.Right := tempRect.Right - 
tempRect.Left * 1; (Adjust to local) 

tempRect.left := tempRect.Right - 18; 

(Do for width of right edge) 

tempRect.Bottom := tempRect.Bottom - 
tempRect.Top * 1; (Get window height) 

tempRect.top := 0; {for height of window) 

EraseRect(tempRect); (Erase old right edge} 

tempRect:= whichWindow^ .portRect; 

(Get window size and position) 

tempRect.Right := tempRect.Right - 
tempRect.Left + 1; (Adjust to local} 

tempRect.left := 0; (Do width of window) 

tempRect.Bottom := tempRect Bottom - 
tempRect.Top + 1; (Get window height) 

tempRect.top := tempRect.Bottom - 18; (Do for 
height of the edge} 

EraseRect(tempRect); (Erase old bottom edge) 

SetRect(tempRect, 20, 20, 1000, 1000); (Min 
Horz size, Min Vert size, Max Horz size, Max Vert size} 

mResult := GrowWindow(whichWindow, 
myEvent.where, tempRect); (Grow it) 

SizeWindow(whichWindow, LoWord(mResult), 
HiWord(mResult), TRUE); (Resize to result} 

DrawGrowIconCwhichWindow); (Draw grow Icon 
again} 

end; (End of doing the growing) 


14 (code - іпбоАнау) then (window goaway area) 
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begin (Handle the goaway button) 

If TrackGoAwayCwhichWindow, myEvent . where) then 
(See if mouse released in GoAway box) 
begin (Handle the GoAway) 
Close-Sample.WindowCwhichWindow, theInput?; 

(Close this window) 

end; (End of TreckGoAway) 

end; (End of InGoAway) 


if (code = inContent) then (See if in a window) 

begin (Handle the hit inside & window) 

if CwhichWindow € FrontWindow) then 
SelectWindow(whichWindow) 

else 
begin (Handle the button in the content) 
SetPortCwhichWindow); (Get ready to аган) 
Do_Sample_Window C myEvent, theInput ); 
end; (End of else} 

end; (End of inContent) 


if (code = inSysWindow) then (DA?) 
SystenClick(myEvent, whichWindow); 


end; (End of MouseDown) 


KeyDown, AutoKey: (Handle key inputs) 
begin (Get the key and handle it) 
with myevent do (menu command keys) 
begin 
chCode :- BitAnd(message, CharCodeMask); 
(Get character) 
ch := CHRCchCode); (Change to ASCII) 
if COdd(modifiers div CmdKey)) then 
(See if Command key is down) 
begin 
mResult :- MenuKey(ch); (menu selection) 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 
1f CtheMenu © 0) then 
(See if a list was selected) 
Handle. My-MenuCdoneF lag, theMenu, 
theItem,theInput?; (Do the menu selection) 
if (Cch = ^x’) or (ch = 'X^») and 
(thelnput © nil) then 
TECutCtheInput); (Handle a TE Cut) 
if (Cch = ‘c’) or (ch = 'C’)) and (theIn- 
put © nil) then () 


TECopyCtheInput?; (Handle а TE Сору) 
16 (Cch = 'v^) or (ch = “V°))and CtheIn- 
put © nil) then 
TEPaste(theInput); (Handle a Paste} 
end 
else if (theInput © nil) then 
TEKeyCch, theInput); 
end; (End for with) 
end; (End for KeyDown,AutoKey) 


UpDateEvt : (Update event Гог а window) 
begin (Handle the update) 
whichWindow := WindowPtr(myEvent .message?; 
(Get the window the update is for) 
BeginUpdateCwhichWindow); 
(Set the clipping to the update area) 
Update_Sample_Window С whichWindow ); 
(Update this window) 
EndUpdate (wh ichW indow); 
(Return to normal clipping area) 
end; (End of UpDateEvt) 


DiskEvt : (Disk inserted event) 
begin (Handle а disk event) 
(Ck for disk event) 
(?? ADD CALL TO HANDLE A DISK INSERTED) 
end; (End of DiskEvt) 
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ActivateEvt : (Window activated event) 
begin (Handle the activation) 
whichWindow := WindowPtr(mgevent . message); 
(Get the window to be activated) 
1f odd(myEvent . modif iers) then 
(Activate апа not DeActivate) 
SelectWindow(whichWindow); 
(Activate the window by selecting it) 


end; (End of ActivateEvt) 
otherwise 

begin (?? ADDED FOR CATCHING OTHER EVENTS) 
end; (End of otherwise) 

end; (End of case) 

end; (end of GetNextEvent) 

until doneF lag; (End of the event loop) 
end. (End of the program) 


unit Sample Window; 


(File name: Sample_Window.Pas) 
(Function: Handle а Window) 
(History: 6/13/88 Original by Prototyper. ) 


interface 


(Initialize us so 811 our routines can be activated) 
procedure Init Semple.Window; 


(Close our window) 
procedure Close Semple.WindowCwhichWindow:WindowPtr; var 
theInput:TEHandle); 


(Open our window and draw everything) 
procedure Open.Sample. Window; 


(Update our window, someone uncovered в part of us) 
procedure Update. Sample. Window(whichWindow:WindowPtr); 


(Handle action to our window, like controls) 
procedure Do_Sample_Window(myEvent :EventRecord; var 
theInput:TEHandle); 


implementation 


const 


I Buttonx1 = 4; (Button ID) 


I_Checkbox! = 6; (Checkbox ID} 
I-Checkbox2 = 17; (Checkbox ID} 
I Rediol = 7; (Radio ID) 
I.Redio2 = 18; (Radio ID) 


I.Edit Text = 3; 
1.5сго11. һаг = 5; 
уаг 
MyWindow:WindowPtr; 
tempRect : Rect; 
Index : Integer; 
CtrlHendle : controlhandle; (Control handle) 
sTemp : Str255; (Get text entered, temp holding) 
RiControl:erray[1..2] of ControlHandle; ( Radio button ) 
TE I.Edit Text: TEHendle; (Text Edit field handle) 


(Edit text ID) 
(Scroll bar ID) 


(Window pointer) 


(Тепрогагу rectangle) 
(For looping) 


(Initialize us so 811 our routines can be activated) 
procedure Init Sample. Window; 


begin (Start of Window initialize routine) 
MyWindow:=nil; (other routines must know not valid yet) 
end; (End of procedure) 


(Close our window) 
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procedure Close.Senple.Window; 


begin (Start of Window close routine) 
if (MyWindow © nil) and (MyNindow = whichWindow) then 
(Close if this is us) 
begin 
if C(theInput = TE_I_Edit_Text) then 
(See if this Text Edit field handle} 
theInput:= nil; (Clear the handle used) 
DisposeWindow(MyWindow); (Clear window and controls) 
MyWindow:=nil; (notify routines window open) 


end; (End for if K(MyWindowOni12) 
end; (End of procedure) 
(=================================) 


(Update our window, someone uncovered а part of us) 

procedure UpDate. Semple. Window; 

var 
SavePort : WindowPtr; (Place to save the last port) 
Pic.Hendle: PicHandle; (Pict handle for pict loaded ) 
sTemp:Str255; (Temporery string) 


begin (Stert of Window update routine) 
if (MyWindow © nil) and (MyWindow = whichWindow) then 
(Handle an open when already opened) 


begin 
GetPort(SavePort); (Seve the current port) 
SetPortCMyWindow); (Set the port to my window) 


Ріс-Нәп”е := GetPicture(9 2; (Get Picture into memory) 
SetRect(tempRect, 188, 141,247,218); 
if (Pic.Handle © nil) then 
DrawPicture С Pic_Handle , tempRect ); 
(Draw this picture} 


TextFont(systemFont); (бей the font to draw іп) 

(Draw а string of text, Static Text } 

SetRect(tempRect, 252, 146,330, 184); 

sTemp :=’Read MacTutor! ^; 

TextBoxCPointerCordCésTemp) + 1), length(sTemp), 
tempRect, teJustLef t2; 

TextFontCapplFont); (Set the default application font) 


(Update a TE box, Edit Text ) 
SetRect(TempRect,46,27,294,129); (left,top,right,bottom) 
InsetRectCTempRect, -2, -2); (Surround the TE area) 
FrameRect(TempRect); (Frame this TE area) 
if CTE_I_Edit_Text © nil) then 
(Only update if TE area is valid} 
TEUpdate(TempRect, TE_I_Edit_Text); (Update TE area) 


DrawControls(MyWindow); (Draw 811 the controls) 
DrewGrowIconCMyWindow2; (Оган the Grow box) 


SetPort(SavePort); (Restore the old port) 
end; (End for if KMyWindowOni12) 
end; (End of procedure) 
(=========s================s===s=====) 


(Open our window and draw everuthing) 
procedure Open_Sample_Window; 
уаг 

Index : Integer; 

dataBounds : Rect; 

cSize : Point; 


(Рог looping} 
(For making lists) 
(For making lists) 


begin (Start of Window open routine} 
if (MyWindow = nil) then 
(Handle an open when not already opened) 
begin 
MyWindow:= GetNewWindowC1,nil, Pointer(-1)); 
SelectWindow(MyWindow); (Bring window to the front} 
SetPor t(MyWindow); (Prepare to write into our window) 
{ Make a button, Button } 
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CtrlHandle := GetNewControlCI.Buttonx 1, MyWindow); 
( Make а checkbox, Checkbox! ) 
CtriHandle :- GetNewControlCI Checkbox 1,MyWindow); 
( Make а checkbox, Checkbox2 ) 
CtriHandle :- GetNewControlCI.Checkbox2, MyW indow); 
{ Маке а radio button, Radio! ) 
RiControl[1] := GetNewControl С I_Radiol , MyWindow ); 
{ Маке а radio button, Radio2 ) 
К1Сопіго1 [2] := GetNewControl С I_Radio2 , MyWindow 2; 
( Make a scroll bar, Scroll bar ) 
CtrlHandle := GetNewControl(I Scroll_bar,MuWindow); 
(Open a TE box, Edit Text ) 
SetRect(TempRect,46,27,294,129); (left,top,right,bottom) 
InsetRect(TempRect,-2,-2); (Surround the TE area) 
FrameRect(TempRect); (Frame this TE area) 
InsetRect(TempRect,2,2); (Restore the original size) 
TE_I_Edit_Text:= TENew(TempRect,TempRect); 

(Create the TE area) 
HLockCHandleCTE. I Edit. Text22; (Lock the handle) 
TE_I_Edit_Text**.txFont := geneva; (Font) 
TE_I_Edit_Text**.fontAscent := 12; (Font ascent) 
TE_I_Edit_Text**.lineHeight := 12 + 3 + 1; 

(Font ascent + descent + leading) 
HUnLock (HandleCTE_I_Edit_Text)); (UnLock the handle) 
sTemp:= ‘Edit Text’; 
(Default text string) 
TESetText(Pointer(Ord4(@sTemp +1), length(sTemp), 

TE_I_Edit_Text); (Place default text in the TE area) 

TEActivateCTE_I_Edit_Text); (Make the TE area active) 
TEUpdateCTempRect, TE. I Edit. Text); 
TextFontCappIFont); (Set the default application font) 
UpDate_Sample_Window(MyWindow); (update draws it) 


end (End for if CMyWindow«>nil)) 
else 
SelectWindow(MyWindow); ^ (Already open, so show it) 
end; (End of procedure) 
(===================s===s===========) 


(Handle action to our window, like controls) 

procedure Do_Sample_Window; 

уаг 
RefCon: integer; (RefCon for controls) 
code: integer; {Location of event in window or controls) 
theValue: integer; (Current value of a control) 
whichWindow:WindowPtr; (Window pntr where event happened) 
myPt :Point; (Point where event happened) 
theControl:ControlHendle; (Handle for а control) 


Procedure Do. A. Button; 

begin 
HiliteControlCtheControl, 10); 
RefCon :- GetCRefConCtheContro1); 
case RefCon of 


(Handle а button being pressed) 


(Darken the button) 
(get control refcon) 
(Select correct button) 


I Buttonx1: (Button, button) 
begin (start for this button) 
??? HANDLE THE BUTTON BEING PRESSED HERE) 
end; (end for this button) 
otherwise (allow other buttons) 
begin (start) 
end; (end of otherwise) 


end; (end of case) 
HiliteControl(theControl, 00; (Lighten the button) 
end; (Handle a button being pressed) 


Procedure Do. A Checkbox; 
var 
Index: integer; 


(checkbox being pressed) 
(Index used for radios) 


procedure Clear 1Кадіобгоир; (clear radios in group 1} 
var 
Index: integer; (Index used for radios) 


begin (Start of the clear routine) 
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for Index := 1 to 2 do (Step thru all radios) 
SetCtlValueCRiControl(Index1,8); (Set this to zero) 
end; (End of the clear routine) 


begin (Handle а checkbox being pressed) 
RefCon :- GetCRefCon(theControl); (дек control refcon) 
theValue := GetCtlValueCtheControl); (Get current value) 
theValue := CtheValue + 1) mod 2; (Change value) 
case RefCon of (Select correct button) 
I Checkbox1: (Сһескһох1, checkbox) 
begin (stert for this button) 
222 HANDLE THE CHECKBOX BEING PRESSED HERE) 
SetCtlValueCtheControl, theValue); 
(Set checkbox to new value) 
end; (end for this checkbox) 


І. Сһескбох2: (Checkbox2, checkbox) 
begin (stert for this button) 
??? HANDLE THE CHECKBOX BEING PRESSED HERE) 
SetCtlValueCtheControl, theValue); 
(Set checkbox to new value) 
end; (end for this checkbox) 


I_Radiol: {Radiol , radio button} 
begin (start for this radio button) 
(??? HANDLE THE RADIO BEING SELECTED HERE) 
CleariRedioGroup; (Clear 811 Radio values) 
SetCtlVaelueCtheControl, 1); (Select Radio) 
end; (end for this radio button) 


I-Radio2: (Redio2 , radio button) 

begin (stert for this redio button) 
(??? HANDLE THE RADIO BEING SELECTED HERE) 
Clear ІКадіобгоур; (Clear 811 Redio ) 
SetCtlValueCtheControl, 1); (Select Radio) 

end; (end for this radio button) 

otherwise (allow other checkboxes and radios) 
begin (start) 
end; (end of otherwise) 
end; (end of case) 
end; (Handle & checkbox being pressed) 


Procedure Do. A. 5сго11Ваг(сове: integer); 
(Handle а ScrollBar being pressed) 


procedure HandleWScrollBar (code, Start, Stop, Increment 
LIncrement : integer; theControl : ControlHandle); 
var 
theValue : integer; 
myPt : Point; 


д 


(Value of the scrollbar} 
(Returned point from track) 


begin 
theValue := GetCtlValueCtheContro12; (Get current state) 
1f (code = inUpButton) then (See if in up/left arrow) 
begin 
theValue :- theValue - Increment; 
if (theValue < Start) then 
theValue := Start; (Bump at the start value) 
end; 


1f (code = inDownButton) then 
(See if in the down/right arrow) 
begin 
theValue :- theValue * Increment; 
if CtheValue > Stop) then 
theValue := Stop; (Bump at the stop value) 
end; 


if (code = inPageUp) then 
(See if in the up/left grey area) 
begin 
theValue :- theValue - LIncrement; 
(Subtract the page increment) 
if CtheValue < Start) then 
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theValue := Start; (Bump at the Start value) 
end; 


if (code = inPageDown) then (down/right grey area) 
begin 
theValue := theValue + LIncrement; (раде increment} 
if CtheValue > Stop) then 
theValue := Stop; (Bump at the Stop value) 
end; 


1f (code = inThumb) then 
begin 
code := TrackControlCtheControl, myPt, nil); 
(Let the 05 drag it around) 
theValue := GetCtlValueCtheContro1); 
(Get current state) 


(drag box erea) 


end; 
SetCtlValueCtheContro!, theValue); (Set new state) 
end; (End of handle scroll bar) 


begin (Handle a ScrollBar being pressed) 
RefCon := GetCRefCon(theControl); (get control refcon) 
case RefConof (Select correct scrollbar} 
I_Scroll_bar: (Scroll bar’, scroll ber) 
begin (start for this scroll bar) 
HandleWScrollBar(code, 1, 10, 1, 18, theControl); 
(code, Min, Max, Inc, PageInc, handle) 


end; (end for this scroll bar) 
otherwise 

begin (stert) 

end; (end of otherwise) 


end; (end of case) 
end; (Hendle а 5сго11Ваг being pressed) 


begin (Stert of Window handler) 
17 (MyWindow © nil) then 

begin 

code := FindWindow(myEvent .where, whichWindow); 

if (nyEvent.what = MouseDown) and (MyWindow = 

whichWindow) then 

begin 
myPt := myEvent.where; (Get mouse position) 
with MyWindow^.portBits.bounds do (Маке it relative) 


begin 
myPt.h := myPt.h + left; 
myPt.v := myPt.v + top, 
end; 


SetRect(tempRect, 46,27, 294, 129); (Position of the ТЕ) 
if PtInRect(myPt, tempRect) then (Check for pressed in 
the TE Edit Text } 
begin 
theInput:= TE_I_Edit_Text; 
TEClick(myPt, FALSE, TE_I_Edit_Text); 
end; 


SetRectCtempRect, 188, 141,247,218); (Position of Pict} 
if PtInRect(myPt, tempRect) then (mouse іп рісі?) 
begin 
( do somethng for mouse click in pict} 
end; 
end; 
1f (MyWindow = whichWindow) and (code = inContent) then 
(for our window} | 
begin 
code := FindControl(myPt, whichWindow, theControl); 
if (code <> Ø) then (Check type of control) 
code := TrackControlCtheControl,myPt, nil); 
1f code = inButton then 
Do_A_Button; 
if code = inCheckBox then 
Do_A_Checkbox; (Do checkboxes} 
1f (code = inUpButton) or (code = inDownButton) or 
(code = inThumb) or (code = inPageDown) or (code = inPageUp) 


(Do buttons} 
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then 
Do. A. 5сго11Ваг(соде); (Do scrollbars) 
end; (End for if KMyWindowswhichWindow2) 
end; (End for if KMyWindowOni 12) 
end; (End of procedure) 


( 
end. (End of unit) 


ЖЖЖЖҖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖ 


RMaker resource file sources. 

File: Prototyper_Sample.R 

History: 6/13/88 Original by Prototyper. 
This file contains the sources for all 
the resources except for Pictures. 


ЖЖЖЖЖЖЖЖЖЖАЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖ 


мими и и ии и и 


Prototyper_Samp le .RSRC 
APPL???? 


x 
* This is the definition for the DIALOG. 
x 


Туре DLOG 
x 

,2 ;;Resource ID 
About Dialog ;,Uialog title 
50 120 189 427 Тор Left Bottom 
Right 


Visible МобоАнау ;, Visible GoAway 
1 


;,ProcID, dialog def 


ID 

2 ;;Refcon, reference 
value 

2 210 of item list 


x 
* This is the DIALOG or ALERT item list. 
x 


Type DITL 
x 


‚2 ;,Resource ID 
2 ;;Number of controls in list 


Button Enabled ;;Push button 
100 102 129 178 ;;Тор Left Bottom Right 
OK ; ¡message 


StaticText ;;Stetic text 

9 10 93 295 ;;Top Left Bottom Right 

Sorry, this program really does nothing. \@0® 1988 
МасТиїог\@0® 1986 THINK Technologies, Inc. Certain portions of 
this software are copyrighted by THINK Technologies, Inc. 
,,hessage 


x 


* This is the definition for the WINDOW. 
x 

Type WIND 

x 


‚1 ;;Resource ID 
Sample Window ;jWindow title 
41 3 305 350 ; Тор Left Bottom Right 
Visible GoAway ;,Visible GoAway 
0 ;;ProcID, Window def ID 
1 ;;Refcon, reference value 


x 
* This is the CONTROL item list. 
х 


Туре CNTL 
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x 


‚4 
Button 
142 46 168 
Visible 
0 


4 
010 


,6 
Checkbox 1 
171 47 193 
Visible 
] 

6 
011 


mu 
Checkbox2 
190 47 212 
Visible 


217 47 242 
Visible 
2 


7 
0 10 


,18 
Radio2 


216 145 241 237 


Visible 
2 


18 
011 


‚9 


129 


137 


137 


139 


;,Кезоугсе ID 

‚Те for a Button 

3, Top Left Bottom Right 
;;Initially visible 

;,ProcID (Control definition ID) 
;;RefCon (reference value) 

;;Min Max Value 


;;Resource ID 

„Тие for a Checkbox 

j; Тор Left Bottom Right 

sj, Initially visible 

33ProcID (Control definition ID) 
;;RefCon (reference value) 

;,Min Max Value 


;;Resource ID 

‚Те for a Checkbox 

Тор Left Bottom Right 
;,;Initially visible 

;,ProcID (Control definition ID) 
;;RefCon (reference value) 

;,Min Mex Value 


;,Resource ID 

;;litle for a RadioButton 

Тор Left Bottom Right 

;, Initially visible 

;,ProcID (Control definition ID) 
; RefCon (reference value) 

;,Min Max Value 


j ¿Resource ID 

;,Title for a RadioButton 

Тор Left Bottom Right 
;;Initially visible 

;;ProcID (Control definition ID) 
;;RefCon (reference value) 

;Міп Max Value 


;,Resource ID 


Scroll bar ;;litle for а Scrollbar 

27 293 129 309 Тор Left Bottom Right 

Visible ;, Initially visible 

16 ;;ProcID (Control definition ID) 
5 ; ;RefCon (reference value) 

1 10 1 ;,,Min Max Value 

x 


* This is the PICTs for the Window list 
* Move the pictures from the resource da 
* after this is compiled. 

* Туре PICT 

x 


* This Picture is Picture 
* 9 


;;PICT Resour 


x 
* This is the definition for the MENU. 
x 


above. 
ta file 


ce ID 


Type MENU 
x 
‚201 ;,Resource ID 
MA ;;АРРЕЕ menu title 
About this Sample... ;;item title 
(- "v 
,202 ;,Resource ID 
File ;,;menu title 
Quit/Q ;;item title 
‚ 293 ;;Resource ID 
Edit ,jmenu title 
Undo/Z ;;item title 
(- T 
Cut /X зет title 
Copy/C зет title 
Paste/V уу item title 
Clear jj item title 
Select All уу item title 
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Basic School 
Matrices in True Basic 


Using Cramer's Rule and True Basic to Solve 
Simultaneous Equations 


It is only a matter of time until each Engineering or Math 
student comes across the need to solve simultaneous equations. 
Fortunately, we live іп a time when someone has already figured 
out the solutions and we can readily use the methods which have 
been discovered. In this column I hope to show how True Basic's 
MAT statements can be used with Cramer's Rule to solve 
simultaneous equations. 

In most areas of engineering, the time comes from time to 
time to solve equations. Many of these solutions can be found 
using a pencil and paper and a little bit of logical thinking. We 
learn from algebra that to solve a set of equations, there needs to 
be one equation generated for each unknown variable. It is the 
responsibility of the engineer to use his expertise in his field of 
study to determine what the equations are. The solution of the 
equations are sometimes trivial, but may take time to manipulate 
the equations with simple algebra. Eventually the answer is 
found. 

Computers are supposed to make life easier. Right? Well, of 
course! Solet'ssee how wecan solve some equations using True 
Basic. First, we need a problem to solve: We want to find the 
current in each of three paths of a circuit. The circuit is shown in 
figure 1. 

To determine the equations which we will use to solve the 
problem we will use Ohm'slaw and Kirchhoff's voltage law. For 
the non-engineer, Ohm's law is a mathematical way to express 
the relationship between voltage, current, and resistance: 

E=I*R 

where R is resistance, E is the voltage across the resistance, 

I is the current through the resistance. This simple law is basic 


10 


Figure 1 
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to a beginning electronics class. Ohm’s law is named after a 
German physicist, George Simon Ohm, who published a pam- 
phletin 1827 which contained the results of his efforts to describe 
and relate currents and voltages mathematically. It has since 
been shown, however, that this result was discovered 46 years 
earlier in England by Henry Cavendish. 

Kirchhoff’s voltage law is named after Gustav Robert 
Kirchhoff, a German university professor who was born about 
the time Ohm was doing his experimental work. Kirchhoff’s law 
states that the algebraic sum of the voltages around any closed 
path in a circuit is zero. I won’t attempt to prove this as there 
are many electronics books which explain how Kirchhoff's 
voltage law works. 

Our first equation is derived by taking the loop shown in 
Figure 2. The path of the loop does is not important as long as the 
path is closed. The equation is: 

-7 + 1(i, - L) + 3 (i, - L) + 1,20 
which equates to: 
i, - 4i, + 4i, = 7. 


Figure 2 


Our second equation is derived by taking the loop where 
current i, is as shown in Figure 1. The equation is: 
1(1,-1)+21, + 3(1,-1) =0 
which equates to: 
-i, - 61, - 31, = 0. 

The last equation comes from the relationship of the current 
source and the currents i, and i: 

i, -i, = 7. 

Now we have three equations and three unknown values to 
solve for. An easy method to use is given by Cramer’s Rule. 
Gabriel Cramer (1704-1752), was a Swiss mathematician, also 
known by his book on the theory of curves, which appeared in 
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1750 іп Geneva. Cramer's Rule states that if we have a system 
of linear equations 


aX, + AX, +...+ a, x = b 


ах, + AX, t... a X m 0, 
with n equations and n unknowns., the n X n coefficient 
matrix of the system is denoted by A. The determinant A #0, the 


components of the solution of the system are given by the 
formula, 


det B k 
det А 


where the matrix B, is the same as A except that the elements 
a 1 <i <n, in Ше kth column of A have been replace by the terms 
b, 1<1< п, respectively. 

Cramer’s Rule says that n simultaneous equations with n 
unknowns can be determined by taking determinants of the 
matrix. Each of the unknowns is calculated as follows: 


1 4; а; 844 ain 
b, а,, а. а, 2. а, 
b3 аз аз аз... аҙ 
baan а аш... а, 
а, а, а, aj а, 
а, а, а, ay - а 
аз 843; 83; алм. азд 
п 4, 85 ам а nn 

апа 
а, bj, аз ац. Fin 
aj b, a, а, "on 
аз: b3 a, аз as, 
а,б, аз ам a an 


11 “12 în 214 in 
a, 922 аз а, an 
аҙ) 835 аз 834 as, 
а al an ay а д... аш 
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and 
а, 4. b, а, ain 
^ а, b, ^ РЕ а, 
а, 83) b, аз. аз 
а nl а 2 b. аы. а nn 
а а, ауу а... a, 
8, %; ад а„.. 8 
а, 8; 23; аз. Asn 
ап ар 2а пз аы а nn 
апі 
a, a, 8,4 ay b, 
a, a, 853 ад b, 
431 432 833 аз b; 
а а „> а n ам 5, 
= === = X 
n 
a, a, 4 8, а 
a, 2а 85 а»... а, 
аз: аз аз; аз... аз, 
where 
a, a, а, ац а in 
а, а, a, а, » a, 
= det А 
аз 835 аз; ам. as, 
a, аю за... а 


The great thing about this is that with True Basic the solution 
is easy to calculate because of the MAT statements included in 
True Basic. MAT statements include MAT INPUT (for inputing 
an array), MAT LINE INPUT, MAT PLOT (plotting to a True 
Basic chart), MAT PRINT (to print a matrix, MAT READ (read 
an array from data statements), MAT REDIM (to reset dimen- 
sions of a matrix), and MAT WRITE (to write an array to a file). 
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The МАТ statement is an enhancement to Basic that is very 
welcome in the scientific/engineering community. It has been 
included for many years in Hewlett Packard Basic (now version 
5.0). 

Using Cramer's Rule by hand the evaluation of the determi- 
nant for i, is: 


-1 6 0 
1 -4 7 
10 7 28 
i, = wawas = нин = 2 
-1 6 -3 14 
1 -4 4 
10-1 


evaluation of the other determinants gives i, 9 Amps and 
iz 2.5 Amps. The evaluation of these determinants are fairly 
easy by hand, but with more equations and more unknowns, the 
it gets to be a lot of number crunching. The program at the end 
will do the number crunching for an n X n matrix, limited by the 
amount of memory you have. The number of equations is 
calculated in a function which uses the factorial function in- 
cluded in the True Basic Libraries to figure how much data is 
available in the DATA statements. The coefficients are entered 
into the DATA statements with equation coefficients in the first 
DATA statement and the solution coefficients in the second 
DATA statement. For solving for a large number of equations/ 
unknowns you may break up the DATA into multiple lines. 

Once the number of equations is determined, the program 
calls the sim solve subroutine to solve the equation. Since the 
MAT statement does all the work, the subroutine is short and 
after acouple of MAT assignment statements, the matrix is ready 
to be crunched. True Basic also supplies us with the det function 
which will automatically calculate the determinant of an n X n 
matrix. It sure beats keeping track of a bunch of numbers by hand 
like I did when I went to school. Calculations are now done and 
our circuit has been analyzed! Now if they would only put a Mac 
on my desk...I could use it! 


| Simultaneous Equation Solver 
! Deve Kelly 
| 01988 MacTutor 


LIBRARY “Fnmlib” 
DECLARE DEF Factr] 


DEF Get Equation-Count 
tions 
WHEN ERROR IN 
LET Counts 
DO 
READ value 
LET Count=Count+ 1 
LOOP 


'Веад the number of eque- 


USE 
RESTORE 
END WHEN 
LET n=0 
DO 
LET п=п+ 1 
LOOP UNTIL Рәсіг1Сп Count 
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LET Count=n- 1 
(ЕТ Get_Equation_Count=Count 
END DEF 


! Start Main Program 

LET numberof __equations=Get_Equation_Count 

DIM 8(2,22,b(2,22,c(2, 1),х(2) 

! Set up 811 the equations 

MAT READ aCnumber_of equations,number. of equations) 
MAT READ cCnumber. of equations, 1) 

MAT REDIM xCnumber_of equations) 

CALL sim.solveCa,b,c,x,number. of equations) 


MAT PRINT x ! Print the solutions 
DATA 1,-4,4,-1,6,-3,1,0,-1 | equation coefficients 
DATA 7,0,7 ! equation data 

END 


SUB sim_solve(aC, ),6С, ),cC, 2, xO, number. of equations?) 
IF det(a)-0 THEN EXIT SUB 
FOR j=1 to number. of equations 
МАТ b=a 
FOR i= 1 to number. ОҒ. equations 
LET bCi, j)=cCi, D 
NEXT i 
LET x(j)=det(b)/det(a) 
NEXT j 
END SUB 


Someone told Dave Kelly that he was a programmer. They 
were kind, but not very accurate. His article “Hierarchical 
Menus & Colors Notes" [VOL. 4 NO. 6] contained more errors 
than accuracies. He claims that ZBasic source code must be 
compiled and the resources attached to make use of them. Why 
not use the function: “RefNum% = ЕМ 
OPENRESFILE(FileName$)”? 

This makes resources available during the programming 
phase and requires the deletion of only one command before 
creating the application. 


The next glaring error was his slap-dash program that should 
have shown how to use submenus from ZBasic.[Excuse me, but 
I showed A way to to submenus from ZBasic, not THE only way. 
Actually, I like your way better now that you have shown it to us. 
Thanks -DK] Ав the following program demonstrates, sub- 
menus do not require special event handling loops, nor is it 
necessary to append special resources. 


“ХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХАХХХХХХХХХА ХАЖ 


d SubMenus from ZBasic 
"“ЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


WINDOW OFF 

COORDINATE WINDOW 

WINDOW 1 

TEXT 0,12,0,0 

PRINTEC 1, 1>”МЕМИ 

PRINTEC 1,3)”I ten!” 

----------5еі The Меги-- 
MENU 1,0, 1, "File^:MENU 1, 1, 1, "Quit/Q* 


SubMenu= 150 
SubMenu 
MENU SubMenu,@, 1, "I^m outa here? ‘We’11 delete this from the 
menu bar as soon as we've attached it to а menu item. 

MENU SubMenu, 1, 1, “Plain/P;Bold/B<B; Italic/I«I;Outline/ 

0«0; Shadow /S«S^ 


'This is the number we^ll use for our 
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SubMenuHnd1&=FN GETMHANDLECSubMenu) ‘Handle to the SubMenu 


“пон delete the name from the menu Баг 

‘CALL DELETEMENUCSubMenu) ‘Cthe menu itself still remains 
available) 

MENU 2,9, 1, “Format” "We^ll add the submenu here 
f 

"Create a menu item with the command key equivalent of 


‘CHR$(27) and mark the item with the number of the 
'SubMenu instead of a “2” for a check mark 


MenuName$- "Style/^*CHR$(C27) 
MENU 2, 1, SubMenu, MenuName$ 
[4 


‘Use а negative insertion number(-1) and the handle to 

‘our SubMenu - the “CALL INSERTMENUCSubMenuHandle, –1)* 
‘should take place immediately after the root menu is created 
[4 


CALL INSERTMENUCSubMenuHnd1&, - 1) 

MENU 2,2,1,"Itz Eazy With Z^ “Add more items and menus if you 
like 

CALL DRAWMENUBAR ‘Redraw the ber to exclude the hidden menu 
(----------Ғуепі5 

ON MENU 00508 “Handle Menu” 

MENU ON ‘We’1]l just track menu events 

“Loop” “Loop and wait 

GOTO “Loop” ‘Getting dizzy? 

MENU OFF 

“Handle Menu” ——— ranu Handling 

Menu ID=MENUC9 ) 

I temID=MENUC 1) 

MENU ‘Get results of the menu action 

IF MenuID=1 AND ItemID=1 THEN END ‘End if user selected 


*Quit^ 

PRINT@C9, 1)MenuID” ы 

PRINT@C9, 3) I temID* * 'Else-Show menu info 
RETURN “Back to the “Loop” 


Wake up, Dave. And try to spend a little time developing 
your programming skills and a little less time throwing rocks. 


Regards 
Chris Stasny 


Well, Chris it seems you have a little chip on your shoulder 
about something (Do you workfor Zedcor? ). In my defense, there 
are many "programmers" outthere that have had trouble getting 
ZBasic event processing to do everything they want it to do. It is 
true that some of the problems have been fixed as the users have 
been debugging ZBasic ever since it was released! In my 


opinion, there is no Basic available today for the Macintosh 
which is satisfactory for doing serious software development as 
there are glaring holes in their capabilities. Г уе had too many 
phone calls from disgruntled developers trying to find a solution 
to their problems with no solution in sight. Call it rock throwing 
if you like, but face it, there isn't any such thing as LightSpeed 
Basic. Thank you for your letter. We encourage others to share 
the technology by writing for MacTutor. We are dedicated to the 
distribution of useful programming information without regard 
to race, creed or developer status. Chris, we never claim to know 
everything. We could use more of your good ideas. Write to 
MacTutor and ask for our authors kit and share some of your 
"expertise". 
Dave Kelly 


I'm a new subscriber to MacTutor and have particularly 
enjoyed your column “Вавіс School". I'm a BASIC programmer 
and frankly don't have the time to really learn the other high level 
languages such as C or Pascal. It is, therefore, heartening to find 
a source of instruction for BASIC on the MAC. 

Do you think it would be feasible to compile your articles 
into a separate volume? I believe such a book would sell quite 
well. There are many recreational and small application pro- 
grammers who both love BASIC and the MAC. Keep up the 
great work. 

Sincerely, 
Julian Wan 


Thank you for your kind remarks. I' ve had several people 
askfor a separate volume of “Basic School" . Because of the cost 
of publishing another compiled book and since we already offer 
the "Best of MacTutor" Vol 1 and 2 for a reasonable price, 
"Basic School" will not become a volume of its own. Have heart 
though, Гуе used information from C, Pascal, and assembly 
language columns many times and so having the other language 
available in "Best of MacTutor" can actually help when writing 
BASIC programs too. I've also compiled a MacTutor Index 
HyperCard Stack which can help when you are trying to learn 
about a specific subject. 

Dave Kelly 


ом 
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Basic Wars and True Windows 


Basic Wars Revisited 

I promised more information about True Basic. First I 
would like you to refer back to MacTutor August 1986, February 
1987 and March 1987 for the previous episodes of “Basic Wars”. 
The following table gives True Basic (Version 2.0) data for most 
of the benchmarks used to compare ZBasic and MS Basic 2.0 the 
last time I ran the benchmark. Please be aware that the math 
operations were corrected in the March 1987 issue. From a 
comparison of the benchmarks we can draw a few conclusions. 
First, True Basic appears to be faster for all math operations even 
though True Basic is not truly compiled. Only Microsoft Basic 
(binary) is comparable in math speed, but does not include the 
accuracy of True Basic. Graphic operations are slower than the 
MS Basic interpreter. Array look up was comparable to compiled 
speeds for MS Basic or ZBasic. String handling approaches 
ZBasic compiled speeds. True Basic ran the Sieve in less time 


than the MS Interpreter, but slower than any of the compiled 
Basics. 


Still keep in mind that benchmarks are not the only way to 
determine the strengths of a language. These results show that 
True Basic performs very well considering that it is not truly 
compiled to native machine code. It would be much more of a 
speed competitor if it was compiled. True Basic’s strengths are 
in other areas which cannot be measured only by benchmarks. То 
some people the other capabilities of True Basic are not enough 
to justify the slow speed. If the only thing you are looking for in 
a language is speed then you'll probably be disappointed. 

True Basic Benchmark: System 6.0 


BENCHMARK Macintosh Plus Macintosh II 
FOR Loop 1.6 sec. .388 sec. 
Array Lookup 20.67 sec 5.25 sec. 
Math Operations 

Addition 22.15 sec. 3.8 sec. 

Subtraction 23.23 sec. 3.55 sec. 

Multiply 25.55 sec. 3.8 sec. 

Divide 39.15 sec. 3.78 sec. 
String Operations 

Concatenation 10.3167 sec. 2.35 sec. 

Matching 12.15 sec. 3.12 sec. 
Graphics 

Line(Basic statement) 

61.25 sec. 15.33 sec. 

Horizontal line 38.867 sec. 12.3 sec. 

Circle 13.4667 sec. 6.63 sec. 

Set Pixel (PLOT) 

119.3 sec. 37.83 sec. 
File I/O (Floppy disk) 
Random READ 
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24.5 sec. 8.2 sec. 
Random WRITE 

43.48 sec. 13.7667 sec. 
Sequential PRINT 

817.0667 sec. 4.3 sec. 
Sequential INPUT 

17.45 sec. 4.533 sec. 

Sieve (1980 primes) 
118.917 sec. 29.0333 sec 


Accuracy Benchmark 
Answer: 503.543802149746 503.5438021499906 
1.224999999999966 1.2299999999999960 
.88333 sec. .166667 sec. 

Some of True Basic's strength comes from the structured 
nature of the ANSI committee standard which it closely follows. 
Rather than go through a blow by blow account of what each 
command in True Basic does (you can always read the manual to 
find out that), ГІ tell you what's new since version 1.0 was 
released. Mostly True Basic is the same very structured, capable 
language as before. From a scientific, engineering and educa- 
tional standpoint True Basic offers the best learning environ- 
ment. It has all the advanced structures of the latest Basics 
available such as SELECT CASE, DO/LOOP with WHILE and 
UNTIL, and multi-line IF/ELSE IF/END IF. True Basic is 
modular in that you can define your own modules which can be 
loaded as required. Local and global variables are supported. As 
discussed last month, True Basic has a full set of matrix algebra 
statements. Arrays are dynamic and resizable. Line numbers are 
now optional. Recursion is supported. Optional variables may 
be declared іп CALLs. 

The built-in editor works very well (unlike the ZBasic 
editor). It is not the best editor in the world, but is adequate. You 
have search and replace (Find and Change) and Include (which 
inserts a file from disk at the cursor point). The annoying little 
stop light (version 1.0) has been removed. You may select 
breakpoints in your program where you want to suspend execu- 
tion to examine variables or'do debugging. There are three 
windows thatare used in the interpreter environment. The source 
window contains the source code, the output window lets you 
save output from several runs of the program if you want, and the 
command window lets you type commands specific to managing 
the interpreter (Actually, True Basic is compiled to b-code for 
extra speed, but since it is not true native machine code I hesitate 
to call it a compiler). You can use almost any True Basic 
statement in direct mode, that is, directly typed into the command 
window. Asimple help system is available, but I feel that unless 
you are a beginner, the help system is next to useless. 
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Script files апа DO programs сап be set up to configure True 
Basic or to automate actions. It’s sort of like having aa set of exec 
files thatcan be executed as short cuts. Since there may be several 
folders containing library files used, you will want to configure 
your disk with a TBStartup file containing an ALIAS statement 
which references all of the places you want True Basic to look for 
library files. This is a very awkward way to do things, but once 
it gets set up you just declare your library and True Basic takes 
care of things for you. (Sort of reminds me of what I don’t like 
about MSDOS). DO programs are used for things such as 
formatting the source code, getting a cross reference list of 
variables, or tracing a programs variables. Since you сап always 
write your own DO program you can set it up however you wish. 

True Basic supports the 68881 coprocessor which speeds up 
calculations quite a bit. We've already seen samples of True 
Basic color capabilities in previous issues of MacTutor. 

Macintosh Goodies 

Macintosh people want their applications to look right and 
feel right for the Macintosh user. True Basic provides a library 
“MacTools*” which contains most of the simple graphics calls: 

call MacPenSize (width, height) 

cell MacPenMode (mode) 

call MacTextFont (font) 

call MacTextFace (style$) 

call MacTextMode (mode) 

call MacTextSize (size) 

call MacTextBox (left, right, bottom, top, $$, just$) 

call MacSpaceExtra Cextra) 

let п = MacStringWidth ($$) 

call MacGetFontInfo Cascent, descent,widmax, leading) 

call MacInvertRect Cleft,right,bottom, top) 

call MacPaintOval Cleft,right,bottom, top) 

call MacInvertOval Cleft,right, bottom, top) 

call MacFrameRoundRect Cleft,right, bottom, top, x, y) 

call MacPaintRoundRect Cleft,right, bottom, top,x,y) 

call MacInvertRoundRect Cleft,right, bottom, top,x,y) 

let name$=MacGetF i le$Ch,v, type$, but ton$) 

let name$=MacPutF i le$Ch,v,pr$, iname$, but ton$) 

call MacSysBeep (duration) 

call copy_clipboard 

call сору_допе 

call copy_pictfile Cfilename$) supports PICT2 format 

call copy_printer( 1) 

call draw_clipboard( 1) 

call Read_cl ipboard( type$, s$) 

call Write_cl ipboard( type$, $$) 

call Read_pictfile(filename$,s$) 

call Write_pictfileCfilename$,s$) 

call Draw_string(s$, fit) | 

These аге basically the same sort of commands available to 
MS Basic users as built in statements. Other statements for 
printer control are also included in “MacTools*” library. True 
Basic file handling is done using the file names with colons 
separating the volume names. If the more preferred method of 
using volume numbers is desired then you should plan on using 
Mac ROM calls. 

The Macintosh Developer's ToolKit supplies the rest of the 


Macintosh interface. The libraries included in the ToolKit 


include: 
TrueWindows* True Windows 
Ехесі ib* Semi-portable system routines 
HexL ib* Integer arithmetic aids 
System* Low-level interface to System 
Мәсі ib* Trap interfaces for other libraries 
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DataLib* Data conversion for ToolKit routines 
ColorLib* Color manager 

Ріскегі ірх Color picker package 
ControlLib* Control manager 

DeskLib* Desk accessory manager 
DialogLib* Dialog manager 

DiskLib* Disk driver 

DiskInitLib* Disk initialization package 
EventL ib* Toolbox/System event managers 
FileLib* File manager 

FontLib* Font manager 

ListLib* List manager 

MenuLib* Menu manager 

Packagel ib* Package manager 

PaletteLib* Palette manager 

QuickL ib* Quickdraw 

ResourceL ib* Resource manager 

ScrepL ib* Scrap manager 

SFP1ib* Standard file package 
SoundL ib* Sound manager 

SystemL ib* System utilities 

TextEditL ib* Text edit 

ToolboxL ib* Toolbox utilities 

WindowL ib* Window manager 


As in version 1.0, some calls cannot be mixed with some 
True Basic commands (especially graphics) very easily. How- 
ever, this is really not to bad considering the problems we've run 
into with ZBasic and keeping Macintosh events separate from 
ZBasic events. Also, the Developer's ToolKit now provides 
some easy menu and window statements for simple applications. 
They call this set of routines, TrueWindows. 

INTRODUCING "TRUE WINDOWS" 

At first it doesn't seem to make a lot of sense to even have 
the TRUE WINDOWS library available, but in a pinch when you 
need a quick and dirty application (what Basic is used for the most 
often), it is good to not have to set up the GetNextEvent Loop. 
True Windows gives you access to menu, dialog and alert, event 
handling and window routines. An example using True Win- 
dows is included with this column. 

True Windows menu statements are set up with DATA 
Statements. The MAT statement makes it easy to read in the 
entire menu in one statement. The array containing the menu is 
dimensioned as DIM menu$(0:menus, 0:items) where menus is 
the number of menus and items is the max number of menu items 
in any one menu. This set up is fairly simple and easy to use. 

A set of 5-6 types of dialog/alert boxes are available. You 
can also set a timeout for the dialog box so that if there is no user 
response the program will continue. Using that function is not 
recommended by the Macintosh user interface guidelines be- 
Cause it allows something to happen which the user has nocontrol 
over and does not expect to happen. 

A True Windows event handler returns menu,refresh, win- 
dow selection, close box events, window move events, window 
resize events, up, down, left, right, pageup, pagedown, pageleft, 
pageright, vscroll, hscroll, single click, double click, triple click 
and mouse down events as only as often as you ask for them. True 
Windows or True Basic does not go out and do a GetNextEvent 
just for the fun of it which in turn messes up your own event 
handling. 

While it is true that True Windows does not do everything, 
it is a way to get Macintosh looking interfaces without a lot of 
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extra work. If it doesn't handle the job then the rest of the 
Developer's Toolkit is sufficient to handle any other jobs that 
might come up that require the Mac ROM routines. And if Apple 
comes out with a new call some day itis very simple to go in and 
add the call yourself just by examining the source code for the 
Toolkit libraries. The copy of Developer's Toolkit that I have is 
a prerelease copy, but it appears to be complete in every way. 
The hardest thing about using any library is to know the 
routines that need to be declared in the DECLARE DEF state- 
ment so that they can be used in your program. All external 
functions must be declared. However, the LOAD statement 
could be used to make the library become a part of the Basic 
language and thus the DECLARE statement would not be neces- 


Ok, so we know that True Basic can do all this stuff, should 
Iuse it for my development project? The answer to this has to be 
answered yourself, but you should ask your self the following 
questions: 

1. Does my program need to run fast? True Basic speed is 
satisfactory for many needs, but there are some things that must 
run faster. | 

2. Do I care if my application program is greater than 73K? 
The runtime package uses 73K of disk space. About 35 K of that 
is in the resource fork of the file and may be shared by more than 
one application by cutting the resources from the application and 
pasting into the system file. This is not the preferred method, but 
could be done if necessary. 

3. Do Ihave a lot of math operations to perform? True Basic 
is extremely strong in its math support. This is especially true on 
the Mac II which also includes 68881 math coprocessor support. 

4. Do I want full access to the entire Macintosh ROM 
routines? The Developer’s Toolkit does a great job of supporting 
all of the ROM routines in a way that can be understood. It is easy 
to add new ROM calls as they are added in the future. You won't 
have to wait for True Basic's next upgrade to have support of the 
new features. It would be nice if the ROM support was built into 
True Basic, but by loading the Library into memory it can 
become a part of True Basic. Besides, even Lightspeed Pascal 
requires that Libraries be declared (in the project window) in 
order to use them. 

In my opinion, True Basic has come a long ways by includ- 
ing the runtime package with the Basic system. I would like to 
see the Developer's Toolkit bundled with the language system, 
though the price would certainly be near the same price anyway. 
Currently, the True Basic language system, including Runtime is 
$99.95. True Basic libraries are $69.95. This makes the com- 
bined package cost $169.90. There are only two areas that I wish 
could be improved upon with True Basic. One would be to have 
atrue compiler that produces real machine code instead of the b- 
code stuff. I realize that the b-code is designed to be able to 
transfer applications in True Basic to other computers. As a 
matter of fact, True Windows routines are supposed to be 
transferable to other computers such as the Amiga (gasp) which 
use a window approach. The other area that could improve is in 
the code size of the runtime package. Some of the size problem 
could be eliminated if a *true' compiler were available, that is if 
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it compiled the code efficiently. 
IColor Picker Demo 
!Demonstrates True Basic’s True Windows and 
lillustrates use of the Color Picker routine 
10 1988 MacTutor 
ІВу Deve Kelly 
LIBRARY “TrueWindows*”, "QuickLib*^, “Ріскегі ib*^ 
LIBRARY *datalib*^, "maclib*^, "systen*^ 
DECLARE DEF H,V,GetColor$, UnpackEnvirons$,RGB$ 
DIM тепи$С0: 1,0:2) 
LET false=0 
LET true=1 
LET Done=false 
CALL tw-initC*COLOR^) 
but I’m ready for it! 
| Find out what kind of computer this is 
CALL SysEnvironsCsysEnvRec$, status) 
CALL UnpackEnvirons(sysEnvRec$, envversion, machine, sysversion, 
processor, hasFPU,hasColorQD, keyboardtype, atversion, 
sysvref num) 
IF hasColorQD<> 1 then 
! we gotta quit, this isn’t a Mac II 
LET done=true 
CALL tw dwarn(3, “Color Quickdraw is not available! 
but you can’t run this 1^, *0K^, l,result) 
END IF 
IF done€ true then 
MAT READ menu$ 
DATA *",About MacTutor Picker Demo...,"^ 
DATA File,Get Picker...,Quit 
CALL tw_menu_set(menu$) 
DO 


| Color isn’t supported yet, 


Sorry, 


| Set up the menu 


CALL tw_event(maxnum, type$ window, menunumber menuitem) 
SELECT CASE type$ 
CASE “MENU” 
SELECT CASE menunumber 
CASE 0 
CALL About 
CASE 


1 
CALL fileCmenuitem, done, inrgb$) 
CASE ELSE 
END SELECT 
CASE ELSE 
END SELECT 
LOOP Until Done=true 
CALL tw_menu_clear 
END IF 
CALL tw cleanup 
END 
SUB about 
! Set up the About dialog box. 
CALL tw.dwernC8, “MacTutor Picker Demo|61988 MacTutor |By 
Dave Kelly”, "0K^, 1,Result) 
END SUB 
SUB fileCmenuitem, done, inrgb$) 
SELECT CASE menuitem 
CASE 1 
! Set up the upper corner of picker dialog 
CALL SetPtCPoint$,0,0) 
! do picker dialog 
CALL GetColor(point$, "Pick a color, just for 
fun!^, inrgb$, outrgb$, okf lag) 
| select the color 
IF okflag=1 then LET inrgb$=outrgb$ 
CALL unpackRGBCinrgb$,r,g, b) 
LET string$=“Color selected 
was: |r="&str$(r &”|g="&str$( gk” Ib="&str$(b) 
! Display the color in rgb coordinates 
CALL tw. dwarnCi,string$, "0K^, 1,result) 


! Get rid of the menus 


| clean up all the TrueWindows stuff 


CASE 2 
LET dones! 
CASE ELSE = 
END SELECT 5] 
END SUB SEED 
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Basic School 


System Snooping in MS QuickBasic 


MS QuickBasic Arrives!! 

It’s been a long wait (nearly a year and a half) but Microsoft 
has finally upgraded their infamous compiler. The best part is 
that it has really improved!! Microsoft took their interpreter 
which has always been an excellent product, and combined their 
compiler to produce what they are calling a new product named 
QuickBASIC 1.0. 

There are some major changes that have taken place and 
many things have remained the same. The programming envi- 
ronment includes the same “pretty-printing” editor (with some 
improvements) which was included in earlier versions of the 
interpreter. There are still two versions of basic, the binary 
version and decimal version. Programs written using earlier 
versions of MS BASIC still function properly and in some cases 
they even work better. When you start listing all of the changes 
you can easily see why Microsoft chose to call it version 1.0 
instead of MS Compiler version 2.0. 

The first obvious change is the manual. MS QuickBASIC is 
now packaged as a shrink wrapped book and disk like their 
competitors. Most of the fancy packaging on software goes in the 
trash most of the time anyway. If removing the expense of the 
packaging lowers the price like it did for this one, I vote that all 
software companies do the same on all their software. QuickBA- 
SIC is priced ага mere $99!! Registered users of either MS Basic 
Interpreter or Compiler may upgrade to MS QuickBASIC 1.0 for 
$40. Upgrades are free to any registered user who acquired either 
of Microsoft's BASIC products for the Macintosh after August 
1, 1988. MS QuickBASIC now requires at least 1 MB of 
memory. Thenew manual includes two books in one. The user's 
guide includes a description of how to use the interpreter/ 
compiler functions, a tutorial on developing programs using 
QuickBASIC, a tutorial on debugging your program, creating a 
stand-alone application, documentation on how to access the 
Macintosh toolbox, and documentation for ResEdit (an older 
version is included with QuickBASIC) and Edit (QuickBASIC 
includes the latest version of the MDS editor which bombs on the 
Mac IT). The second part of the manual is the BASIC Language 
Reference which includes a description of Basic variables, syn- 
tax, a statement and function reference, and appendix. The 
appendix contains documentation for invoking ROM routines 
and the Toolbox library, also some very good information about 
creating your own Libraries (similar to the old BMLL document) 
including how to write your own routines from Assembly, C or 
Pascal. Instructions are also given to install your own icon after 
compiling your stand-alone application. 

The menu bar has now changed. As a matter of fact, when 
programs are run, a default menu is used which includes File and 
Edit menus. QuickBASIC removes its own menus so you no 
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longer have to clear the menus when running your program as in 
earlier versions. Using the compileroptions, you may disable the 
default menu and window for compiled programs. 

The ‘Search’ menu contains new menu items, ‘Get Info’ and 
"Set Info' which allows the user to add new items into the Help 
data base, or add comments to the help that already exists. The 
text added is stored in the BASIC source code itself so Help can 
be different for different programs. It is not known if the Help 
text can be moved from one source code file to another. The ‘Set 
Info' item cannot be found in the manual and in some respects 
does not seem to work properly. Once it even corrupted the 
default help info which is stored in the QuickBASIC application. 
Itis handy to type cmd-I (Get Info) while editing and get a dialog 
explaining the command that the cursor is pointing to. Another 
nice feature is the bookmarks. Y ou can set a bookmark to force 
BASIC to remember the page that you are on so you can return 
there quickly. 

The interpreter is able to help debug your program. For 
example, before executing the program, breakpoints may be set 
by inserting a stop sign icon. When the program stops at a 
breakpoint, or encounters anerror, the value of key variables may 
be displayed. (This smells like Lightspeed doesn'tit?) You may 
then change the value of any variables and continue execution. 
The highlighted tracing option which was available in earlier 
versions of MS Basic is still available in QuickBASIC too. 


SSS Listing of "Cones" Бе ГДЕ 
01988 Microsoft Corp. 
Example from the User's Guide 


HHH 
229392 
ede LH 


DEFINT a-z 
SH=SYSTEM(6) ‘Get screen height d 
SW=SYSTEM(5) ‘Get screen width | 
һ%-150 ШІ 
w%=400 n 
WINDOW 10, ((SW-w8)/2,(SH-h$)/3)-((SWw-w3: 
title$="Cones” HH 
TEXTFONT O HHE 


НЯ 
REH 
9 0000, 
НЕЗ 


М 0 V ET DAI ЕНІН 


HII 
$*$*$* 
H 


RAARRKHAAE KRHAAHHKRAAKRAHAARHAHARKRARARKRARAARRRARRAAANR 
HIII HITITE е #11 ИШИ ИШ 1 Hui 99959 ЕНІ 4922 
%%%:08099989090909%990999090909000999%:0900090224000092000,02090 
229298299990909595029990104290994009979099990929099949%9 
BSH SESS EHS SS SESE rrr SS ESS ES SETS ty 
U4-0-0-023-0-0-0-0-0£3-0-0-0--0-0-0-0-O-0-0-U0-0-0-0-O-U-U-039- 0-01 


Н 95949 
tt ЭП 11111111111 ЖШЖИН ШИЖ 
Аня 


B 


Figure 1. Example Listing 


One of the most needed enhancements was HFS support. 
Now, MS Basic is smart enough to find files anywhere. If you 
have a LIBRARY statement you don't have to include the full 
path name because the first time your program is run, if Quick- 
BASIC can't find your library file, it asks you to look for it. Then 
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it does something even better. After you find the file for 
QuickBASIC, the path is stored away automatically in your 
source code file and used the next time the program is run. There 
may have to be some slight modification to some programs 
written in earlier versions of BASIC, so QuickBASIC provides 
away to disable the File Not Found Dialog option in the ‘Options’ 
menu item of the ‘Run’ menu. 

The compiler is built in so it is very easy to get a stand-alone 
application up and running. There are several options available 
when compiling, including 68020 and 68881 support if you can 
use it. Most of the same compiler options are available here that 
were available in MS Compiler 1.0. As mentioned before, you 
may choose to use the default window or use the default menus 
(File and Edit) if needed. Library resources may be included if 
the ‘Include MBPCs and MBLCS' option is selected. (All the 
CLR Toolbox libraries have been updated and the resource type 
changed to MBLC (Microsoft Basic Library Code????) re- 
sources. The MBPC type is used to denote pure code resources 
which can be created with some compilers. A utility program is 
included to scan a QuickBASIC source file and remove library 
and toolbox resources which are not used by the application. This 
will reduce the size of the stand-alone application. ALSO, the 
toolbox library (formerly called ToolLib) is now installed as 
MBLC resources in the QuickBASIC application. Therefore, all 
the toolbox statements are available at all times. You now need 
to specify a type ('&','', ЯҒ) for a library call only after 
DEFSTR; DEFINT no longer requires a type. For example: 


DEFINT a-z 
DrewText "No more exclamations on library invocations!” 


There have been several new MBLC routines added to 
QuickBASIC since the last release of MS BASIC. One of these 
new statements 15 the Toolbox statement which allows access to 
other Toolbox ROM routines which are not specifically available 
as MBLC routines. You will need Inside Macintosh to make full 
use of this statement. Routines marked NOT IN ROM are not 
accessible from QuickBASIC with the ToolBox call. You must 
write an MBPC or MBLC to do this. The syntax for the ToolBox 
statement 15: 

ToolBox calltype$, trapnum%, argi, arg2, ... , argn 

The calltype$ argument is a BASIC string variable indicat- 
ing the type of the ROM call. Procedures are indicated by either 
“Р” or "S", Functions returning boolean results use “В”, func- 
tions returning integers use “W” and functions returning a long 
integer (LONGINT) use “L”. The trapnum% is the trap address 
of the ROM routine as found іп Inside Macintosh. A few samples 
are given in the manual of some ROM calls. The number of 
arguments in the ToolBox call will vary depending on the routine 
that is called. 

Sample programs using the ToolBox call are shown below. 
The first program shows a call to the ROM routine that gets the 
names of fonts if given an id. The program really isn’t of much 
value except to demonstrate an example use of the ToolBox call. 
[Make sure to remove all non-printable fonts from the system 
(i.e. postscript escape fonts) or it will crash; I think it has 
something to do with zero width fonts.- ed] The second program 
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uses the ToolBox call to get the Macintosh tick count. By using 
this the benchmark times could have been measured more accu- 
rately. The remainder of the program demonstrates the use of the 
SYSTEM function. The SYSTEM function is used to get system 
environment information for your program. Getting screen size 
is one use of the SYSTEM functions available. Other environ- 
ment information is also available as shown in the program. 
These functions and the ToolBox calls are explained in more 
detail in the QuickBASIC manual. 

Your old CLR libraries and other libraries you may have 
created can still be used with QuickBASIC without converting 
them to the MBLC resource type. Be sure to check to see if the 
routine already exists in QuicKBASIC as a MBLC before using 
your old routine unnecessarily. You may print lists for compari- 
son purposes with the new version of the Statement Mover 
program. Statement mover has also been updated to support the 
MBLC and MBPC resource types. 

You’re probably wondering how QuickBASIC does in the 
benchmark tests. Table 1 shows the benchmark results for 
QuickBASIC , True Basic and ZBasic. ZBasic and True Basic 
times have appeared in previous issues of MacTutor and were not 
retested for this table. I have included them here for comparison 
purposes. Keep in mind that any one benchmark test does not 
determine how good a language is. All tests were performed on 
a Macintosh Plus Computer. 


BENCHMARK MS QuickBASIC* True Basic ZBasic 
FOR Loop (Real) З sec 1.6 sec. 15 sec. 
Array Lookup (static) 2 sec. 20.67 sec. 1 sec. 
Math Operations 

Addition 9 sec. 22.15sec. 52 sec. 

Subtraction 10 sec. 23.23 sec. 64 sec. 

Multiply 12 sec. 25.55 sec. 211 sec. 

Divide 35 sec. 35 sec. 446 sec. 
String Operations 

Concatenation 34 sec. 10.3167 sec. 10 sec. 

Pattern Matching 25 sec. 12.15 sec. 6<өс. 
Graphics 

Line (Basic stmt) 7 sec. 61.25 sec. 6 sec. 

Horizontal line 15 sec. 38.867 sec. 5 sec. 

Circle 20 sec. 13.4667 sec. 15 sec. 

Set Pixel 

(PSET or PLOT) 38 sec. 119.3 sec. 19 sec. 
File /О (Floppy Disk) 

Random READ 2 sec. 24.5 sec. 8 sec. 

Random WRITE 24 sec. 43.48 sec. 114 sec. 

беді. PRINT# 3 sec. 17.0667 sec. 9 sec. 

Seql. INPUT 3 sec. 17.45 sec.  ??? 


Sieve of Eratosthenes 8 sec. 
Accuracy Benchmark 
X 503.54380215  503.54380215 503.54380215 
S 1.23 1.224999999999966 1.23 
time =1 sec. 88333 sec. 4 sec. 


118.917 sec. 7 sec. 


* NOTE: QuickBASIC compiled binary version used for all 
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tests except accuracy benchmark. 


To obtain optimal performance from compiled QuickBA- 
SIC for execution speed it is advisable to use static arrays, turn 
off array bounds, turn off event checking, generate 68020 and 
68881 code if applicable, use SELECT CASE statements instead 
of IF/THEN/ELSE statements inside loops, and use SHARED 
(global) arrays when passing to subprograms. 


Display Fonts 

€Copyright 1988 MacTutor 

by Deve Kelly 

This program will display all your system fonts 
with а semple end by name. 

This progrem uses the ToolBox statement in 
QuickBASIC version 1.0 


Üw - -. а % а а 


ToolBox “I” 
DEFINT a-z 
x=0 
FontName$=*” 
FOR 1=0 TO 254 
TEXTFONTCi) 
GOSUB GetFontsname 
IF FontName$ € ^^ THEN 
PRINT “This is a sample of font #7; 
CALL TEXTFONTCQ):PRINT i;^ %;FontName$ 
IF х/10 21 THEN 
х-0:РКІКТ "Click mouse button to continue...” 
WHILE MOUSEC0) O 1 :WEND:CLS 
ELSE 
х=х+ | 
END IF 
END IF 
NEXT 
WHILE MOUSEC@)<> 1: МЕМО 
END 


‘ Initialize Toolbox 


‘ Cycle through all the fonts 


GetFontsname: 
ТгарМо%-%НАВЕР 
ToolBox "P^,TrapNo$,Ci2,FontName$ 
RETURN 


‘Get the name of the Font with ID = i 


“ System Configuration Demo 

701988 MacTutor 

‘ By Dave Kelly 

* This program displays all of the system configuration 
"^ data which is returned by the SYSTEM Function. 

' Also the number of tick counts is read from the 

‘ Macintosh directly to get а more accurate time. 


ToolBox “I”: ‘Initialize the toolbox call 
Star t&=0&: f inish&=0& 
CALL GetTickCount(star t&) 
screenwidth=SYSTEM(5) : ‘ get screenwidth 
Screenheight=SYSTEM(6) : ” get screen height 
WINDOW 1, "System Configuration”, (4, 41)-(Screenwidth-8, Screen- 
height-8), 1 
PRINT “Macintosh System Version: *; SYSTEMCO) 
machineszSYSTEMC1) : “деб machine type 
SELECT CASE machine 
CASE 0 
machineType$- "Unknown" 
CASE 1 
пасһіпеТуре$= “Мәс 512K” 
САЅЕ 2 
machineType$="Mac Plus" 
3 


:’Call the tick count routine 


machineType$-^Mac SE" 
SE 4 


machineType$="Mac II" 
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END SELECT 
PRINT “Machine type: *;machineType$ 
PRINT “Running QuickBASIC version *;SYSTEMC2) 
Math-SYSTEMC3): * Get Math type 
SELECT CASE Math 
CASE 0 
MathType$="Binary Math” 
Е 1 


MathType$-"Decimal Math” 
END SELECT 
PRINT “Using *;MathType$ 
env ironmentF 1ag-SYSTEMC4) 
IF environmentFlag-9 THEN 
PRINT “Program is being run from the QuickBASIC 
environment” 
ELSE 
PRINT “Program has been compiled.” 
END IF 
CALL GetTickCount(f inish&) 
PRINT “Total time to run this program was *;(finish&-start&)/ 
60; ^ seconds” 
END 


SUB GetTickCount(Ticks&) STATIC: Get the real number of ticks 

ТгарМо%-%НА975 

Ticksk=0& 

ToolBox "L^, Тгар№ %, Ticks& 

END SUB 
LETTER BAG... 

Yourreview of True Basic 2.01 was of special interest to me 
because I've been trying to port a library of thirty astronomical 
programs from CBasic (remember?) and MS Basic to the Mac. 
As you pointed out, the math libraries and advanced toolkits 
make True Basic very useful for scientific tasks. However, the 
many arbitrary differences in syntax from standard Basics has 
made the translating task very time-consuming and the source 
level debugging using DO TRACE is crude compared to 
MacPascal or LSP. 


My greatest disappointment has been the poor speed per- 
formance. My Mac has the Turbomax accelerator board and 
68881 coprocessor both ratedat 16 mhz. Since my work involves 
heavy use of transcendentals, I use the Savage benchmark; here 
are some results: 


MacPescal 2.0 
True Basic 2.01 
Excel 1.04 

LS Pascal 1.1 


30.1 seconds 
29.1 seconds 
12.6 seconds 
4.7 seconds 


interpreted 
x 


Supports 68881 
compiled 


ж This is "It's even faster than before." as their ad claims? 

Incidentally, they carefully modified the Geneva font so that 
the capital О and zero (0) are identical; a real ‘gotcha’ when 
trying to debug. —Leonard Kalish 


Maybe QuickBASIC will be better for you as it can be 
compiled. Also if you use CLR Libraries MathStatLib you get 
some of the math routines back. The difference in the Basic 
syntax is because of the ANSI standard influence of Thomas E. 
Kurtz, one of True Basic’ s authors. It is interesting that most of 
the other Basics out there are enough different from the ANSI 
standard to make translating a difficult task. Thanks for your 
comments. DK. v 


Sol 


A 
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fasic School 


QuickBasic's Statement Mover 


Statement Mover Fix 
During the past month, I've been looking at the demo 
programs included with MS QuickBASIC 1.0. The programs 
exercise most of (but certainly not all) the syntax of QuickBA- 
SIC. Also utility programs are provided which can be used to 
help your development are: | 


* AlertMover' For copying Alert/Dialog resources 
*Cursor Editor' For defining your own cursors 
‘Demo Resources’ containing Alert resources 


'extra MBLC Remover' removes unnecessary library re- 


Sources from your application programs. 
*Pattern Editor' For defining your own patterns 
"Print Listing File' Print listings created at compile time. 
'renumber CODEs' avoids code id conflicts 

*SortSub' moves sub programs to the end of a 
Basic source code file 

‘Statement Mover’ moves resources especially Library 
resources. 


Missing from this list is a variable cross reference program 
and a program to compare the differences between two text files. 
Comparing differences between files is somewhat complex 
when programs don’t have line numbers to compare with. 

The new version of ‘Statement Mover’ is much improved 
over the version included with MS BASIC 3.0 and the CLR 
Libraries. You can now copy most any kind of resource that has 
a resource name attached. But, don't open up an open resource 
file or you get a bomb! That means you can’t open the System 
File or the ‘Statement Mover’ application. I haven't worked on 
a fix for that one yet, but I have made a minor improvement to 
‘Statement Mover’ which uses a dialog resource. 

The routine I have written replaces the NewTypeDialog 
subprogram in 'Statement Mover'. First the program's volume 
reference number is retrieved and the dialog is displayed. Then 
a loop is set up to retrieve changes in the modal dialog. When a 
radio button is pressed the routine responds to it and updates the 
other buttons. The buttons represent a set of resource types 
which might be moved from one program or file to another. The 
edit field is updated with the resource type so that it will be passed 
when the routine is exited. 

The dialog resource may be created with ResEdit or any 
other program that allows you to create dialogs. I used Proto- 
Typer™ to create the dialog so that I could try it out before I 
copied it into my QuickBASIC program. Because I had so many 
buttons in my dialog I used ResEdit to adjust the order of the 
buttons so that the “ОК” button would be the first one (Proto- 
Typer™ sets them up in the order that they were drawn and you 
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can’t change the order without starting over). 

Another thing that this dialog resource shows is a way to 
create the bold default buttons. Normally in Pascal or C you can 
draw the bold with the FrameRoundRect statement after defining 
the dialog item as a user item. A method that works is to define 
a PICT resource that looks like the bold roundrect and position 
it around the button which will be the default (usually the ‘OK’ 
button). I believe that you can do it this way from other languages 


too, although Inside Macintosh vol. 1 says to use the user items. 


^ NewTypeDialog Subprogram 

' Replaces NewTypeDialog in Statement Mover Program 
‘ Subprogram by Dave Kelly 

* Portions derived from Prototyper. 


'Use these lines to test the progrem 

’ сапсе1%-0 

“МенТуреф-”” 

' CALL NewTypeDialog(NewType$, сәпсе1%) 
' PRINT NewType$ 

' END 


SUB NewTypeDialog(NewType$,cence13) STATIC 
False-0:True-NOT False 
ExitDialog =False ” Flag used TO EXIT the DIALOG 


Selection&=8 : ‘ DialogPtr;NAME of DIALOG 
index%=8 :’ FOR looping 

EditString$="" :’ GET Text entered, temp holding 
itemHit$=0@ : ' GET selection 


‘ Start of DIALOG handler 
vref$=SYSTEM(7): ” Get program’s volume reference number. 
МенТуреф-”” 
GetNewDialog vref£,10000,Selection& ' Bring in the 
DIALOG resource 
ExitDialog=False ” 
itemH i tZ=0 
WHILE ExitDialog=False ” Start of DIALOG Handle loop 
ModalDialog Selection&, itemHitZ :’ WAIT until an 
item IS hit 
SELECT CASE itemHitz 
CASE 1 ‘ Handle the OK BUTTON being pressed 
ExitDialog=True ‘ (EXIT the DIALOG when This 


Do NOT EXIT DIALOG Handle loop yet 
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selection IS made) 
cance 1%=False 
CASE 2 ! Handle the Cancel BUTTON being 
pressed 
ExitDialog=True “ (EXIT the DIALOG when This 
selection IS made) 
SetDialogText Selection&, 4, "^ 


cance 1%=True 


CASE 5 TO 27 
FOR index$-5 ТО 27 ' CLEAR ALL other radios 
IF index% itenHit$ THEN SetDialogBut 
Selection&, index$, 1 
NEXT index% 
‘ Setup the Dialog selections 
SetDialogBut Selection&, itemHitg,2 
IF itemHit%=5 THEN EditString$z"ALRT^ 
IF itemHitS=6 THEN EditStr ing$=*APPL” 
IF itemHit%=7 THEN EditString$- "BNDL^ 
IF itemHit%=8 THEN EditString$-"CNTL^ 
IF itemHit%=9 THEN EditString$-"CURS^ 
IF itemHit%=10 THEN EditString$z^DITL" 
IF itemHit$211 THEN EditString$-^DLOG^ 
IF itemHit%=12 THEN EditString$s"DRVR^ 
IF itemHit%=13 THEN EditString$z"FOND^ 
IF itemHit%=14 THEN EditString$s^FONT^ 
IF itenHit$-15 THEN EditString$-^FREF^ 
IF itemHit%=16 THEN EditString$-^GNRL^ 
IF itemHit%=17 THEN EditString$-^ICNt^ 
IF itemHit%=18 THEN EditString$-^ICON^ 
IF itemHit$=19 THEN EditString$- "MBAR^ 
IF itemHit%=20 THEN EditString$z^MENU^ 
IF itemHit%=21 THEN EditString$="PAT’ 
IF itemHit%=22 THEN EditString$="PAT#” 
IF itemHit%=23 THEN EditString$z^PICT^ 
IF itemHit%=24 THEN EditString$-"SIZE^ 
IF itemHit%=25 THEN EditString$z^STR'^ 
IF itemHit£-26 THEN EditString$-^STR * 
IF itemHit%=27 THEN EditStr ing$="WIND” 
SetDialogText Selection&, 4,EditStr ing$ 


CASE ELSE 
FOR index$-5 ТО 27 ” CLEAR ALL radio buttons 
SetDialogBut Selection&, іпдех%, 1 
NEXT index% 


END SELECT 
МЕН) ‘ Handle DIALOG items until EXIT selected 
GetDialogText Selection&, 4,NewType$ 
DisposeDialog Selection& ‘ Flush the DIALOG out of 
memory 


END SUB ' END of unit 


The following Dialog resource file should either be 
created with Compiled with a resource compiler or recreated 
with ResEdit or Prototyper. 


resource ‘PICT’ (600, purgeable) 


0), 
; 139; 1; 0; 10; 255; 255; 255; 255; 0 
; 0; 3; 0; 3; 11; 0; 21; 0 
; 0; 


1 
(17; 1; 160; 0 
1 
1 1; 0; 35; 0; 70; 160; 0 


; 35; 0; 70: 
; 21; 64; 0; 
; 131; 255) 


resource ‘DITL’ (10000 , "NewTypeDialog^) 


(130, 146, 156, 207), 
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Button (enabled, "OK^); 
(130, 26, 155, 88), 

Button (enabled, “Сапсе1”); 
(120, 246, 136, 297), 

StaticText (enabled, *Other:^); 
(120, 306, 136, 357), 

EditText (enabled, *^); 
(20, 26, 42, 90), 

RadioButton (enabled, "ALRT^); 
(40, 26, 60, 81), 

RadioButton (enabled, "APPL^); 
(60, 26, 82, 90), 

RadioButton (enabled, "BNDL^); 
(80, 26, 102, 90), 

RedioButton (enabled, "CNTL^); 
(100, 26, 120, 81), 

RedioButton (enabled, "CURS^); 
(20, 96, 42, 160), 

RadioButton (enabled, "DITL^); 
(40, 96, 62, 160), 

RadioButton (enabled, "DLOG^); 
(60, 96, 82, 160), 

RadioButton (enabled, "DRVR^); 
(80, 96, 102, 160), 

RadioButton (enabled, "FOND"); 
(100, 96, 122, 160), 

RadioButton (enabled, "FONT^); 
(20, 166, 40, 221), 

RadioButton (enabled, "FREF^); 
(40, 166, 62, 230), 

RadioButton (enabled, "GNRL^); 
(60, 166, 80, 221), | 

RadioButton (enabled, "ICNI^); 
(80, 166, 100, 221), 

RadioButton (enabled, ^ICON^); 
(100, 166, 120, 221), 

RadioButton (enabled, "MBAR^); 
(20, 236, 40, 296}, 

RadioButton (enabled, "MENU^); 
(40, 236, 62, 300), 

RadioButton (enabled, “PAT “); 
(60, 236, 80, 291), 

RadioButton (enabled, “PAT#); 
(80, 236, 102, 300), 

RadioButton (enabled, "PICT^); 
(100, 236, 120, 291), 

RadioButton (enabled, “517Е7); 
(20, 306, 40, 361), 

RadioButton (enabled, "'STRI^); 
(40, 306, 62, 370), 

RadioButton (enabled, "STR “); 
(60, 306, 80, 361), 

RadioButton (enabled, "WIND^); 
(123, 139, 161, 212), 

Picture (enabled, 600) 


J; 


oe “106” (10000 , "NewTypeDialog^) 


(50, 120, 223, 504), 


invisible, 
noGoAway, 

0x1, 

10000, 
*NewTypeDialog^ 


); 


I came across a bug in the AlertMover program which I 
include a fix here. The problem was that AlertMover would not 
save to an existing file. There are some fundamental problems 
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with some of the sample programs on the QuickBASIC examples 
disk which are related to finding the filename of the application 
program. Microsoft added the SYSTEM(7) function after the 
manual was printed and so was probably not known or available 
at the time the demo programs were written. Changes could be 
made to the other programs in a similar manner. Here is the fix: 


WAS: 

AlertMover 

€ Sharon Zardetto Aker 

€ 1988 by Microsoft Corp. 

Modified from Sharon Zardetto Aker's original to take 
advantage of new QB features. 


м . 2 а а ` а = 


CLEAR, 100000% 
OPTION ВАЗЕ 1 


SH=SYSTEM(6) 
SW=SYSTEM(5) 


'Get screen height 
'Get screen width 


IS: 

AlertMover 

€ Sharon Zerdetto Aker 

€ 1988 by Microsoft Corp. 

Modified from Sharon Zerdetto Акег”5 original to take 
advantage of new ОВ features. 


Modified again so that it would create new files properly 
by Deve Kelly 9/17/88 


` а 2 ` а UI ` ` ` 


CLEAR, 1000008 
ОРТТОМ ВАЗЕ 1 


DIM SHARED І0РВ%(60),Ғ119 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


: "used by new subprogram 


SH-SYSTEMCO) 
SW-SYSTEMCS) 


“бей screen height 
“бей screen width 


WAS: 


IF ЗҮЗТЕМС4) THEN ‘If compiled.. 
OpenResFile “Demo Resources”, ref 
ELSE ‘if interpreted, get File reference number of this 
source 


ref $-PEEKWC&HA5DA) 
D IF 


E 
ON BREAK GOSUB quit :BREAK ON 
MENU 1,0, 1, "File" 
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IS: 
(4 
ir SYRTENG THEN 
ref%= SYSTEMC7) 


GetPathName ref%, PomName$ 
parse PomName$,path$ — “separate file name from the 


‘If compiled... 


path 
OpenResF ile PgmName$,ref% 
ELSE ‘if interpreted, get File reference number of this 
Source 
ref $-PEEKWCEHASA) 


END IF 
ON BREAK GOSUB quit :BREAK ON 
MENU 1,0,1, File" 


Then add the following subprograms to the end: (These 
routines were taken from the ‘GetPathNames’ demo program 
which is included with MS QuickBASIC version 1.0). This is a 
great way to find the pathnames of files you are using. 


‘ Gets the full path name of а file given the file reference 
' number of file. The file reference may be obtained from 

f OpenResfile, SYSTEMC7), GetChanRefNum, or various low 

Қ memory locations. 


SUB GetPathName(ref%, path$) STATIC 
fil$z^^ : Folder$s^^ 
GetFCBInfo IOPBS(8), f i1$,ref% 
path$=fil§$ 
Dir ID&=10PB%C29 )*65536%+ ТОРВ%С30) 
VRef Num%=I0PB%(26 > 
WHILE Dir ID&<> 1 
GetCatInfo I0PB%(8),Folder$, Dir ID&, VRef Nun 
path$=Folder$+’:“tpath$ 
Dir ID&=10PB%(58 )*65536%+ IOPB£C51) 
WEND 
END SUB 


SUB parse(f ilename$,path$) STATIC 
index%= 1 
WHILE index 700 
las t%=index% 
index¥=INS ТКС index$* 1, fi lename$, ": 4) 


WEND 
IF last%=1 THEN ‘there was no path 
path$="" 
ELSE ‘divide filenamein$ into path$ and 
f ilename$ 


peth$-LEFT$Cf ilename$, last) 
f ilenane$-RIGHT$Cf i lenane$,LENCf i lename$)-1ast3) 
END IF см! 
END SUB 


сыы?» 
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Forth Forum 
A SCSI Driver in Forth 


“An experimental SCSI driver in Mach2” 

This column almost didn’t make it in time. Believe it or not, 
but while testing the SCSI driver of this article, my Quantum 
Q280 gave up. No, read on, it wasn’t the software. (How could 
itbe MY software, anyway?) The interface board let go, and there 
was my most recent version of the driver, on the disk, inacces- 
sible, me dummy having made no backup for the last 2 days. Left 
with ‘only’ а20 MByte Seagate drive, I was going through а поп- 
trivial exercise on how to debug a SCSI driver on the same disk 
which is used for developing it. You cannot imagine the strange 
things that can happen when booting from a disk with a partially 
functioning driver; it sometimes forces you into doing absolute 
no-nos such as booting from a floppy and attaching the SCSI 
connector afterwards so you can re-install the driver without 
getting la bombe immediately. At least, the development cycle is 
slowed down appreciably, since every other time you'll have to 
boot from a floppy. 

Anyway, here it is. The listing contains the Forth source of 
a SCSI driver which is more or less a translation of Apple’s 
assembly source into Масһ2. It is quite long, and I’m not going 
through all of it in detail, having explained the function of most 
of the routines in my lastcolumn. One added feature is error retry; 
if a SCSI error happens, the offending command is repeated up 
to ten times. 

The driver takes 50% more space than the assembly version 
and is about half as fast. So, you may ask, why go through all this 
trouble? You might have noticed the title ‘An experimental SCSI 
driver’. The code is meant for you to experiment with, add 
features - such as better error recognition and correction, multi- 

volume support, anything you may imagine. Or translate part of 

the routines into C or assembler. I just felt it was necessary to have 
a functioning example of a SCSI driver in some ‘higher-level’ 
language to make changes easier. 

From the Forth point of view, I added a number of compiling 
words and glue routines that may be helpful for you in developing 
other things. 

You already know the words :XDEF, ;XDEF, and XLEN 
from the Hypercard article. For easier programming of drivers 
and desk accessories, Inow added :DA, ;DA, and DALEN which 
define the header of a driver, fill in the header after its definition 
is complete, and return the total length of the driver. 

Since the SCSI driver code is jumped to at the beginning, it 
looks like other definition procedures from the outside, and its 
definition is therefore embedded between : XDEF and ;X DEF. 
In its interior, the SCSI driver contains a real DRVR, with is 
bracketed between :DA and ;DA. You recognize the glue code 
for the Open, Close, Control, Status and Prime routines at the end 
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of the listing; the glue routines have been simplified by introduc- 
ing macros for register save/restore and eventual jumps to the 
JIODone routine. 


The Prime routine 

Prime is the only one that has to be explained in more detail 
here since it has been modified with respect to the description 
given in the last issue. I added an error retry loop, and transfer of 
the SCSI data in variable size chunks. The code as printed takes 
127 sectors on each read or write, that is, any amount of data 
larger than that will be transferred using several calls to the 
SCSICommon routine. This has been worked out empirically; 
larger transfer sizes would not work on the ST225N (which 
would result in files » 64K not being copied on a Finder copy). 
Your disk drive may allow larger sizes or need smaller ones; 
check this out if you like. You might also want to change the 
Read/Write Extended to a simple Read/Write command, or use 
a multi-transfer SCSI instruction block. The driver is certainly 
not generic and might need such adjustments to work on your 
disk. 

SCSI Installation 

The installation part has been changed slightly, and you'll 
have toreplace parts of the installer code given in the last column. 
First, Ichanged the device and partition maps such that the driver 
Starts at block 4 and the Macintosh volume partition at block 16. 
This is where the Apple Hard Disk installation program seems to 
expect it, therefore you can easily replace this driver with the 
Apple driver in case of problems, without haveing to reformat the 
disk. Furthermore, I added a small routine that will install the 
driver code in the system heap and call it so that it gets installed 
in the unit table; this is an easy way of testing the driver without 
writing it to disk. You can even install the same disk that you are 
using to write the program, in which case you will be left with two 
drive icons on the desktop, referring to the same disk. For testing, 
this is OK, only don’t work too much in such an awkward 
configuration. 

Ihope this series of two articles has given you some ideas on 
how to write your own SCSI driver for your particular device. If 
someone comes up with a good examples for controlling a tape 
streamer - we’re always open for contributions, as you know. 


Feedback Dept. 

Someone read my complaints about the missing editor in 
Mach2; a letter with a disk arrived here recently: 

“Dear Mr. Langowski, 

I'm afraid I'm nota fan of Forth [Oh... JL]. I ike the idea of 
a stack-based language but there's an impenetrable jargon bar- 
пег... Besides, I just don't like typing shifted characters, like #, 
1, % and so on. So I stay home with Pascal and Assembler. 
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On the other hand, I always at least glance at your column in 
MacTutor (as well as every other article that isn't Mac II- 
specific). In the October issue, you say, 'It is a shame that a 
powerful development system like Mach2 still lacks a reasonable 
integrated editor. At least multiple windows should be pos- 
sible... My standard development system is Mach2.13 with its 
editor and Mockwrite, plus Edit under Switcher if required.’ I'm 
stunned. The idea of using Mockwrite in a development system! 
The Mach2 editor must be really bad [ It's not bad for what it 
does, i.e., has no major bugs; but I admit its features are limited 
- JL]. 

I had an editor problem myself, working with TML Pascal. 
TML won't really run under the Switcher; it demands too much 
memory. So if I make a syntax error, I have to transfer to the 
editor, which means quitting the compiler and launching the 
editor, fix the error, then quit the editor and re-launch the 
compiler. Then I can re-compile. Something of a pain, particu- 
larly since error-free code is somewhat rare, at least when Pm the 
coder! [This sounds familiar. JL] My solution: Afterthought, a 
desk accessory programming editor. Now I fix bugs without 
leaving the compiler. 

My problem is solved, and yours may be as well. I'm sending 
you a copy of Afterthought. It will open large files (up to 8 
Megabytes), two ata time. It has most of the features of MDS Edit 
- the most significant exception is Replace АП. And it's reasona- 
bly fast. At the very least, it is better than Mockwrite! 

Sincerely, 

Clifford Story, Jimmy Mac Software, P.O.Box 957, 
Murfreesboro, Tennessee 37133." 


Thank you, Clifford, for developing a product that - I guess 
- many of our readers have been waiting for. 

The disk contained the Afterthought desk accessory, its 
manual, some update notes and examples, a demo version, and a 
demo version of Idealiner, an idea processor written by the same 
author. The prices are, by the way, extremely reasonable; $20 for 
the editor and $40 for the idea processor. To find out more about 
these products, send mail to the above address, or GEnie mail to 
CLIFF. 


The second editor desk accessory product that I find worth 
mentioning is JoliWrite, written by Benoit Widemann from 
Paris, a small (32K limit) text editor that is extremely useful for 
working with bulletin board services. Often, when you prepare a 
text off line for a BBS message, you wish to be able to enter the 
text free-format and then format into lines of so and so many 
characters, with paragraph indentation and justification if de- 
sired. Also, over here it is often necessary to convert accentuated 
characters from Macintosh into ASCII representation and back, 
andin general you might wish to be able to remove/add line feeds, 
clip off numbers from line starts, etc. Joli Write does all that, and 
in addition is one of the few products that supports Undo on all 
operations. By the time you read this, an English translation of 
JoliWrite (shareware, 120F/US$20) will hopefully be available 
on the Macintosh section of GEnie. 
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Listing 1: An experimental SCSI driver 


С € 1987 J. Langowski / MacTutor 2 
only forth definitions 
also mac also assembler 


CODE SCALE 
MOVE.L — (A62*,D0 
BMI.S @1 
MOVE.L (A6),D1 
ASL.L 00,01 
MOVE.L 01, (Аб) 
ЕТ5 

61 MOVE.L  (462,D1 
NEG.L DO 
ASR.L 00,01 
MOVE.L 01,(А6) 
RTS 

END-CODE 

: 4ASCII 0 
4 0 DO 


8 SCALE 0 WORD 1+ Сё + LOOP 


) 


( *** compiler support words for external definitions *** ) 
: :xdef 
create -4 allot 
$4EFA w, C UMP D 
би, C entry point to be filled later ) 
0, С length of routine to be filled later ) 
here 6 - 76543 


: ;Xdef ( branch marker entry | - ) 
marker 76543 € abort^ xdef mismatch" 
entry branch - branch w! 
here branch - 2* branch 2* ! 


: xlen 4 + 6 ; С get length word of external definition ) 
( *** driver header block *** ) 


0 CONSTANT drvrF lags 
2 CONSTANT drvrdelay 
4 CONSTANT drvrEMask 
6 CONSTANT drvrMenu 
8 CONSTANT drvrOpen 
10 CONSTANT drvrPrime 
12 CONSTANT агугС+1 
14 CONSTANT drvrStatus 
16 CONSTANT drvrClose 
18 CONSTANT drvrname 
50 CONSTANT DAlength 


( *** compiler support words for DA and driver definitions *** 
) 
: :DA 
create -4 allot 
here 87654 ( start of DA block, and marker ) 
54 allot С length of block 2 


2 


: ;DA ( DAstart marker Ropen Rprime Есі1 Rstatus Rclose 
Rf lags Rdelay Remask Rmenu Rname | - } 
marker 87654 «€» abort? DA definition mismatch” 
Ropen ПАбізгі - DAStart drvrOpen + w! 
Rprime DAStert - DAStart drvrPrime * w! 
Вс DAStart - DAStart drvrCt] + w! 
Rstatus DAStart - DAStart drvrStatus + w! 
Rclose DAStart - DAStart drvrClose * w! 
Rflags DAStart drvrFlags + w! 
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Rdelay DAStart drvrDelau + w! 

Remask DAStart drvrEmask * w! 

RMenu  DAStart drvrMenu + w! 

Rname count dup DAStart drvrName + c! 
DAStert drvrName + 1% swap 
dup 31 > if drop 31 then cmove 

here DAstart - DAStart DAlength + ! 


, 


: DAlen DAlength + ё ; С get length word of external defini- 
tion 2 


ұ-------::------- 
\ some macros needed in the driver 


CODE xchg С exchange word halves on top of stack ) 
move.] Ca62*,d1 
swap.w di 
move.] 91,-(аб) 
rts 
END-CODE MACH 


CODE min 
MOVE.L (A62*,D0 
CMP.L (A62,D0 


BGE.S 61 
MOVE.L 00,(А6) 
61 RTS 


END-CODE MACH 


CODE sh! С data “bits ) 
MOVE.L (A62*,D0 
MOVE.L (A62,D1 


LSL.L 00,01 
MOVE.L 01, (Аб) 
RTS 


END-CODE MACH 


CODE shr С data “bits ) 
MOVE.L CA6)+,D0 
MOVE.L (A62,D1 


LSR.L 00,01 
MOVE.L D1,CA6) 
RTS 


END-CODE MACH 


CODE w* 
MOVE.L CA6)+,D1 
MOVE.L (А62%,00 
MULS.W 01,00 
MOVE.L D0,-CA6) 
RTS 

END-CODE MACH 


V **** DA glue macros 


$8FC CONSTANT JioDone 


CODE DA.prelude 
LINK Аб, 1-5 12 ( 512 bytes of local Forth stack ) 
MOVEM.L А0-А1,-САТ) С save registers ) 
MOVE.L A6,A3 € setup local loop return stack ) 
SUBA.L #256,АЗ 
MOVE.L А0,-СА6) ( perameter block ) 
MOVE.L A1,-CA6) С device control entry ) 
RTS V just to indicate the MACHro stops here 
END-CODE MACH 


CODE DA.epi logue 


MOVE.L (А62%,00 С return code ) 
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С in the low 256 local stack bytes ) 


MOVEM.L (A72*,A2-A1 С restore registers ) 
UNLK A6 
RTS 

END-CODE MACH 


CODE DA.JIODone 
MOVE.L САб)+, 00 С ге{игп соде ) 
MOVEM.L (А72%,Ай-А1 С restore registers ) 
UNLK Аб 
поуе.1 JIODone, Ad 
movem.1 d4-d//84-86,-CaT) 


jsr (ай) 
тоует.1 (а7)+, 94-97 /а4-аб 
КТ5 


END-CODE MACH 
‚ trap Newptr,sys,cir $A71E 


V fields of device control entry 
4 CONSTANT dCtlFlags 

6 CONSTANT dCtlQHdr 

16 CONSTANT dCtiPosition 
20 CONSTANT dCtlStorage 
24 CONSTANT dCtlRefNum 
26 CONSTANT dCtlCurTicks 
30 CONSTANT dCtlWindow 
34 CONSTANT dCtlDelag 

36 CONSTANT dCtlEMask 

38 CONSTANT dCtlMenu 


N parameter block constants 


CONSTANT qLink 


V ptr to next queue entry( long word] 
CONSTANT «Туре 


4 V queue type [word] 

6 CONSTANT ioTrap V routine trap [word] 

T CONSTANT ioTrep*1 — N read or write command 

8 CONSTANT ioCmdAddr \ routine address [long word] 
12 CONSTANT ioCompletion \ addr of completion routine 
16 CONSTANT ioResult N result code returned here 

18 CONSTANT ioNemePtr \ pointer to file name string 
22 CONSTANT ioVRefNum N volume reference number 

26 CONSTANT csCode С type of control call ) 

28 CONSTANT csParam € control call parameters ) 


\ MFS 1/0 Perameter Block 
24 CONSTANT ioRefNum 

26 CONSTANT ioVersNum 

21 CONSTANT ioPermssn 

28 CONSTANT ioMisc 

32 CONSTANT ioBuffer 

36 CONSTANT ioReqCount 
40 CONSTANT ioActCount 
44 CONSTANT ioPosMode 

46 CONSTANT ioPosOffset 
50 CONSTANT IOParemBlkSize 


4ascii ЗОВУ constant “sdrv 
4ascii TFS1 constent “tfs1 


N Equates 
V My excuses Гог the format. This has been taken almost 
V ‘as is’ from Apple's SCSI driver exemple. - jl - 


EQU verChar $34 X version 74” 
EQU SCSIZE 10 \ size of SCSI extended command 


N Equates for our storage (pointed to by DCtlStorage) 
EQU Offset Ø N [long] offset of starting sector 
EQU МУ00Е1 Offset*4 
\ [20 bytes] drive queue element (with flags) for this drive 
EQU MyDrvNum — MyDQE1*20 

V [word] drive num (determined by scanning drive queue) 
EQU NextAddr MyDrvNum+2 
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EQU 
EQU 


EQU 
EQU 
EQU 


EQU 
EQU 


EQU 
EQU 
EQU 


N [long] ptr to current block buffer 

TickleFlag NextAddr +4 

\ [byte] Do we need to remind the system about this drive? 
BlindOK TickleF lag+ 1 

N [byte] Can we use blind reads? 

V І left this in to keep the format the same. 

N We don’t need it since our driver does not read blind. 
SCmd BlindOK+! 

N [16 bytes] SCSI extended cmd Block /JL 


StatWord 5Ста+ 10 

[word] status and message bytes... 
MsgWord StatWord+2 
\ [word] ... returned by SCSIComplete 
Our ID MsgWord+2 X [word] our SCSI ID 
SCSIPseudo OurID*2 


\ [36 bytes] SCSI pseudo-code program 
V 7 three instructions long 


SCSIPar1  SCSIPseudo*2 \ first SCSI code paramr (long) 
SCSIPar2 SCSIParit+4\ 2nd SCSI code parameter (long? 
DiskVarLth SCSIPseudo*(SCSIZE*3) 


N length of our locals... 


EQU DQDrvSize 12 


EQU realSizeMyDQE1+DQDrvSize+4 


N equates for CSParam offsets for our special control call 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
. EQU 


EQU 
EQU 
EQU 
EQU 


DSCCmd CSParam 

\ Ptr to SCSI command block 

DSCPseudo DSCCmd+4 \ Ptr to SCSI pseudocode Cif any 
bytes to xfer) 


DSCBuffer  DSCPseudo*4 X Ptr to buffer for transfer Cif 
anu) 
DSCSize DSCBuffer*4 N Size of transfer, signed (+ if 
read, - if write) 
DSCTicks DSCSize+4 N Tick count we're willing to wait 
| for completion 
DSCCmdSize DSCTicks*4 X (word) Size of command block we're 


sending Cusually 6) 


KillCode 1 
VerifyCode 5 
FormatCode 6 
EjectCode 7 
IconCode 21 
AccRun 65 
SCSICode 77 . 
V our own special code (def ined above) 


ControlErr -1 


StatusErr -] 
ParamErr -50 
nsürvErr -56 
nsVErr -35 
ioErr -36 


dNeedTime  $DFFF 
V to clear bit 5 of high byte in drvrFlags 


DiskInsertEvt 7 
SysEvtMask $144 
UTableBase $11C 
DrvQHdr $308 


QHead $2 
000г1уе 6 
DQRefNum 8 
DOFSid 10 
PDSig 0 
PDSigWord $5453 
PDFSID 8 
PDLen 12 
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\ The code starts here. 


: ХОЕР ScsiDisk 
\ compiles а jump to the install code at the end 
V which will be resolved at the end of the definition. 
:рА DiskDrvr 
V this word provides the driver header structure 


. ALIGN 


X 0200 Icon, аз given by Quantum 


V If you find this ‘snail’ ugly, feel free to change it ... 


\ У.Е. 


header SCSIIcon 


DC.L $00000000 
DC.L $00000000 
DC.L %003ҒҒС00 
DC.L $?1FFFF80 
DC.L $07Е007Е0 
DC.L $92800 1Р0 
DC.L 91Ғ0000Ғ8 
DC.L $1E000078 
DC.L $1E000078 
DC.L $1E000078 
DC.L $0F0000F0 
DC.L %07С003Е0 
DC.L $03F80000 
DC.L $00FFFFF8 
DC.L $000FFFF8 
DC.L $00000000 


DC.L $00000000 
DC.L %000ҒҒ000 
DC.L $@@FFFF00 
DC.L $63FFFFC0 
DC.L %ФҒҒҒҒЕҒЙ 
DC.L $iFFFFFF8 
DC.L $3FFFFFFC 
DC.L $3FFFFFFC 
DC.L $3FFFFFFC 
DC.L $3FFFFFFC 
DC.L $1FFFFFF8 
DC.L $0FFFFFFO 
DC.L $07FFFFF0 
DC.L $01FFFFFC 
DC.L $003FFFFC 
DC.L $00000000 


DC.L $00000000 
DC.L %000ҒҒ000 
DC.L %00ҒҒҒҒ00 
DC.L $03F81FC0 
DC.L %07С003Е0 
DC.L %90Ғ0000Ғ0 
DC.L $1E000078 
DC.L $1E000078 
DC.L $1E000078 
DC.L 91Ғ0000Ғ8 
DC.L $0F8001F0 
DC.L %07Е007Е0 
DC.L $01FFFFFO 
DC.L $003FFFF8 
DC.L $00000000 
DC.L $00000000 


DC.L $00000000 
DC.L $003FFCO0 
DC.L $0 !FFFF80 
DC.L $O7FFFFEO 
DC.L $OFFFFFFO 
DC.L $1FFFFFF8 
DC.L $3FFFFFFC 
DC.L $3FFFFFFC 
DC.L $3FFFFFFC 
DC.L $3FFFFFFC 
DC.L $1FFFFFF8 
DC.L $@FFFFFF0 
DC.L $03FFFFF8 
DC.L $OOFFFFFC 
DC.L $000FFFFC 
DC.L 900000000 


N Our “Where:” string 


DC.B 
DC.B 
‚ ALIGN 


11 
“0200 (SCSI)’ 


N SCSI handler glue routines 


“2 


CODE SCSIReset ( - result code 
CLR.W -CA7) 
MOVE.W 80,-(АТ) 
-SCSIDispatch 
MOVE.W (А72%,00 
EXT.L 00 
MOVE.L 00,-СА6) 
RTS 
END-CODE 


CODE SCSIGet ( - result code ) 
CLR.W -CAT) 
MOVE.W #1,-CAT) 
-SCSIDispatch 
MOVE.W (А72%,00 
EXT.L 00 
MOVE.L 00,-(А6) 
RTS 
END-CODE 
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CODE SCSISelect € TargetID - SCSIErrorResult ) 
MOVE.L САб)+, 00 
CLR.W -САТ) 
MOVE.W 00,-САТ) 
MOVE.W 32,-CATD 
-SCSIDispatch 
MOVE.W САТ2%,00 
EXT.L DØ 
MOVE.L D9,-CA6) 
RTS 

END-CODE 


CODE SCSICmd С buffer count – SCSIErrorResult ) 
MOVE.L (А62%,00 
MOVE.L CA6)+,D1 
CLR.W -CA7) 
MOVE.L D1,-CA7) 
MOVE.W 00,-(АТ) 
MOVE.W "3,-CA7) 
-SCSIDispatch 
MOVE.W CA7)+,D8 
EXT.L DO 
MOVE.L 00,-CA6) 
RTS 

END-CODE 


CODE SCSIComplete С waitTicks mess stat – SCSIErrorResult ) 
CLR.W -CAT) 
MOVE.L (А62%,-САТ) 
MOVE.L CA6)+,-CAT) 
MOVE.L (А62%,-САТ) 
MOVE.W #4,-CA7) 
-SCSIDispatch 
MOVE.W (А72%,00 
EXT.L 00 
MOVE.L 00,-САб) 
RTS 


END-CODE 


1 CONSTANT SCInc 2 CONSTANT SCnoInc 
3 CONSTANT SCAdd 4 CONSTANT SCMove 
9 CONSTANT SCLoop 6 CONSTANT 5СМор 

1 CONSTANT SCStop 8 CONSTANT SCComp 


\ main driver routines start here 


: SCSICommon 
V written to emulate the SCSICommon 
\ routine in Apple's example 
N as closely as possible. 
( pseudo cmdblock ourVars ticks bytes cmdsize 
| writing mess stat - result ) 


SCSIGet 0= IF 
ourVers ourID * we 
SCSISelect 0= IF 
cmdBlock cmdSize SCSICmd 0= bytes AND IF 
pseudo bytes Ø< N bytes «0 if writing 
IF (call) SCSIWrite drop 
ELSE (call) SCSIRead drop THEN 
N Note: Your system may be able to support blind transfers. 
\ Here 1$ the place to experiment with such things - 
THEN 


ticks ^ mess ^ stat SCSIComplete 
0= IF 
stat $FF AND IF ioErr 
( there was ап SCSI error ) 
ELSE Ø € successful completion ) THEN 

ELSE € complete unsuccessful 2 ioErr 

THEN 

ELSE € select unsuccessful ) ioErr 
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THEN 


ELSE ( get unsuccessful ) ioErr 
N 


: DiskClose ( parblk dce | - result ) 
0 С result code = OK ) ; 


: diskControl ( parblk dce | ourVars - result ) 
dce DCtiStorage + 6 -> ourVers 
parblk csCode + нё 


killCode OF 0 ENDOF 
verifyCodeOF 0 ENDOF 
formatCodeOF 0 ENDOF 


ejectCode OF 
ourVars MyDrvNum + we 
N check drive # in request 
parblk IOVRefNum + иё = N the same? 
IF 
SysEvtMask иё IF C we're not at boot time ) 
DiskInsertEvt 
MuDrvNum ourVars + we 
(call) PostEvent drop 
ELSE ( boot time ) 
1 ourVars tickleFlag * c! 
( drive will be remembered after boot ) 
THEN 
controlErr 
ELSE nsDrvErr 
THEN 
ENDOF 


iconCode ОҒ [°] SCSIIcon parblk csParam + ! 
0 ENDOF 


eccRun OF 
ourVars tickleFlag * cé 
ourVars offset + 6 B= not 
( we have а good partition ) 
AND 


IF 
DiskInsertEvt 
MyDrvNum ourVars + we 
(call) PostEvent drop 
THEN 
0 асе DCtlDelay + w! 
dce DCtlFlags * dup we 
dNeedTime AND swap и! (С clear flag ) 
0 ourVars tickleFlag * c! 
0 ENDOF 


scsiCode OF 
perblk dup DSCPseudo + 6 
dup DSCCmd * e 
ourVars 
dup DSCTicks * e 
dup DSCSize * e 
DSCCmdSize + we 
SCS ICommon 
ENDOF 


С otherwise ) 
controlErr 


ENDCASE 


: DiskStatus ( parblk асе | - result ) statusErr ; 


CODE GetSysPtr 
move.] (аб )+,а0 
-newptr,sys,clr 
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поуе.1 ай,-(аб) 
rts 
END-CODE 


CODE AddDrv С dae refnum drv# | - 2 
поуе.1 (а6)+, 40 
моуе.] (аб)+,91 
swap.w d 
move.w 41,00 
move.] (аб)+, аб 
_AddDr ive 
rts 
END-CODE 


: DiskOpen ( parblk асе | 
ourVars thisQElem driveNum dqe SCSIprog - result ) 


DiskVarLth GetSysPtr dup 
V get memory for local variables 
-> ourVars dce DCtlStorage + ! 
\ and store pointer to it 
100 5 DO N find unused drive 8 
DrvQHdr QHead + ё -> thisQElem N scan queue 
BEGIN thisQElem 0= IF i leave THEN 
\ end of queue? we have а good number 
thisQElem DQDrive + we 
i © WHILE 
N keep scanning as long as # is not in use 
thisQElem С QLink + ) @ -> thisQElem 
REPEAT 
LOOP -> driveNum 
driveNum ourVars myDrvNum + w! 
\ remember drive * in local vars 
V C following text taken from Apple's generic driver ) 
\ Add а drive to the drive queue. First, some fun facts: 
\ The drive queue element starts four bytes before the DQEPtr! 
N These four bytes contain "hardware-locked^, “ejectable”, and 
V “disk-in-place” info. 
\ 


N Not As Interesting But Still True: HFS supports volumes 

N >32М8,4е5, but since the daDrvSize field in the DQE is only 
\ а word, the Software Gurus had to resort to bizarre sorcery: 
V If the qType field (formerly unused in DQE’s) is 1, the word 
V following the dqDriveSize field is assumed to be the high- 
order 

\ word of а LongInt block count! (dqDriveSize is still the 
low- 

\ order word). It works even if the size doesn’t require both 
\ words, so we always до it this way. 


\ 
\ See: Tech Note 836. 


ourVars М,00Е1 + 8 over w! 
\ set non-ejectable and clear the rest 
2+ Ø over ж! 2+ -> dae 
\ this is the real start of the DQElem 
1 dge аТуре + w! \ large vol queue type 
0 аде daDrvSize +! N no size yet 
0 аде dQFSID + w! \ normal file system 


йде 
dce DCtlRefNum + мё 
driveNum AddDrv X add drive to queue 


N now set up SCSI pseudo program in driver's local vers 


ourVars SCSIPseudo + -> SCSIprog 
scnoinc SCSIprog w! 
scstop SCSIprog scsize + w! 
9 N result code = good 
; 
: DiskPrime ( parblk dce | 
ourVars sectors bytes start size r/w sect transferred 
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error 


- result ) 


асе dCtlStorage + 6 -> ourVars \ setup local var pointer 
1 ourVars TickleFlag + c! 


\ convert byte count into number of sectors 
parblk IOReqCount + 6 9 shr $IFFFFF AND -> sectors 

V convert starting position into sector number 
dce dCtlPosition + @ 9 shr $1FFFFF AND -> start 


ourVers realSize + 6 xchg -> size N get drive size 
start sectors + size 1+ < IF С valid request 2 
0 -> transferred 
ourVars С offset + ) @ +> start 
\ offset by start of partition 


parBlk IOTrep*! + сё 3 = ( is this а write command? 
IF -1 -> г/м %2А00 ( SCSI extended write ) 


ELSE 1 -> г/м $2800 С SCSI extended read ) 
THEN 


ourVars SCmd + w!\ put the command away 


BEGIN С transfer loop ) 


\ If you have problems getting the SCSI transfer to work 

\ with your particular disk, try changing the number of 

\ sectors transferred on each call ( 127 here ) 

\ or change the read/write extended to а normal read/write. 


) 


N Note that in that case you’1] have to change the command 


\ block setup as well. 


127 sectors min -> sect 
transferred +> start 
parbik IOBuffer + 6 transferred 9 sh! + 
ourVars SCSIPeri + ! 
sect 9 shl dup -> bytes 
ourVars SCSIPar2 + ! \ set 8 of bytes 
start ourVars SCmd + 2* ! 
V set starting position in command block 
bytes 2/ ourVars SCmd + 6 +! \ set # of sectors 


ГОЕгг ( preset, if loop with retry is unsuccessful ) 
10 0 00 С retry max 10 times ) 
ourVers SCSIPseudo + 
ourVars SCmd * 
ourVers 60 r/w 10 
SCSICommon 0= IF drop Ø leave THEN 
1 (call) sysbeep \ just for debugging, 
\ beeps if SCSI did not complete successfully 
LOOP -> error 
-127 +> sectors 
sectors 1- 0% 
UNTIL € transfer loop 2 
error dup 0= IF 
parBlk IOReqCount + 6 -> bytes 
bytes parBlk IOActCount + ! 
V we trensferred the # of bytes requested 
bytes dce DCtlPosition * *! 
THEN 
ELSE IOErr 
THEN 


CODE DrvrInst С unitNum | - ) 


поме.1 (a6)+,d9 


not.w d 
Drvr Install 
rts 


END-CODE 
CODE DrvrRem C unitNum | - ) 
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move.] Ca62*,d0 


not.w dd 

-DrvrRemove 

rts 
END-CODE 


CODE openMe ( drvrNeme | result - ) 
\ allocates а parameter block on the АТ stack and calis 
V the _open trap. This is easier to do in assembly - 
moveq.1 *CIOParamBlkSize/2)-1,d0 
61 clr.w -<Са?) 
абга 40,061 
move.] а7,а0 
тоуе. 1 (a6)+,IONamePtr'(a0) 
_Ореп 
add.w ЗІОРагатВ1К512е,87 
поуе.1 99,-(аб) 


rtis 
END-CODE 
: RealInstall 
V This routine is called by the system boot code with 
V the SCSI ID of the disk in D5 and a pointer to its 


V pertition тар іп Ай. We therefore need some special glue 
code. 
N Note that Mach2 allows to do the stack parameter / local 
N variable declaration after this glue code without any 
problems 
LINK Аб, 8-5 12 ( 512 bytes of local Forth stack ) 
MOVEM.L А2-Аб /02-07, -САТ) ( зауе registers ) 
MOVE.L Аб, АЗ ( setup local loop return stack ) 
SUBA.L 4256,43 
MOVE.L A0,-CA6) 


С partition table pointer ) 
MOVE.L 05,-(Аб) 


С SCSI ID 2 
( partition ID | unitNum hdce dce ourVars pt - ) 


ID 32 + -> unitNum 
unitNum DrvrInst \ allocate DCE and install it 
unitNum 4 w* UTableBase @ + @ -> hdce X dce handle 
hdce 6 -> асе N get асе pointer 
(71 DiskDrvr dce С DCtlDriver + ) ! 
\ put pointer to driver into (се 
[^] DiskDrvr drvrFlags * we 
dce DCtiFlags + w! 
Y move driver flags, RAMbase should be cleared 
Ø dce DCtiDelay + w! \ no time needed yet 
(71 DiskDrvr drvrEMask + e 
dce DCtiEMask + ! X move event mask and menu 


(71 DiskDrvr drvrName + openMe \ try to open this driver 

IF € not OK 2 unitNum DrvrRem 

[*) Scsidisk (са11) DisposPtr 

bre 61 N exit hack. 

V This is the Mach2 equivalent of the 

N Ugly Goto Statement in Pascal. 

\ Sorry, but it is so much easier this way... 
THEN 


hdce ё -> асе 
X дегег this handle again, may have changed 
dce dCtiStorage + 6 -> ourVars 
ID ourVers ourID * w! 
partition IF 
V well, we should have а non-NIL partition at least... 
partition С PDSig + ) w@ PDSigWord = IF 
\ and it should be a Macintosh one. The NEW Apple drivers 
\ have a different sig word and DPM format that you 
\ might want to take into account here (see text). 
partition 2+ -> pt 
BEGIN 
pt PDFSID + 6 ?dup WHILE 
\ otherwise no good partition found 
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С in the low 256 local stack bytes ) 


"tfsi = 
IF С correct file system ID ) 
pt @ ourVars Offset + ! 
pt 4 + @ xchg 
С long drive size, hi word <-> 10 word ) 
ourVars realSize + ! 
SysEvtMask w@ 0= IF X we're booting 
dce dCtlFlags + dup we 
$2000 OR swep w! 
С set dNeedTime flag 2 
1 dce dCtlDelay + w! 
1 ourVers TickleFlag * c! 
THEN 
THEN 
12 +> pt 
REPEAT 
THEN THEN 


61 UNLK A2 N which was used for local variables 
MOVEM.L CA7)+,A2-A6/D2-D7 С restore registers ) 
UNLK A6 
RTS 
\ we stop here; the rest will be inaccessible junk (4 bytes). 


2 


: DrOpen DA.prelude DiskOpen DA.epilogue ; 

: DrClose DA.prelude DiskClose DA.epilogue ; 
: DrCt1 — DA.prelude DiskControl DA.JIODone 

: DrStatus DA.prelude DiskStatus DA.JIODone ; 
: DrPrime DA.prelude DiskPrime DA.JIODone ; 


4 


a 


DrOpen ' DrPrime * DrCtl ° DrStatus ° DrClose 
$6700 Ø Ø Ø С flags delay mask menu ) 

* .SCSIfth^ С name, MUST start with а period ) 
‚ОА 

7 


“ RealInstall ;XDEF 


V The following routines are to be added or replaced in the 

N installer program from the previous column. Included is ап 
V installer that will directly move the Forth code to disk, 
without 

\ going through а resource, and some code to install the 
driver 

\ in memory for testing without writing it to the disk. The 

X DDM and DPM definitions have been changed somewhat 

\ to accommodate the larger driver, and to have the partition 
stert 

\ at the same place that Apple's new SCSI driver expects it 
(so 

Y that you can replace the Forth driver easily by а new Apple 
\ driver in cese you аге fed up with this hack) 

V Good luck. - JL - 

\ 


һех 


: create .ddm 
ddm 200 9 fill 
4552 ddm w! 
read.cap дат 2+ w! ( block size ) 
ddm 4 + ! ( # of blocks ) 
0 ddm 8 + w! С device type ) 
0 ddm А + w! С device ID ) 
10 ddm C + ! С first data block ) 
1 ddm 10 + w! С one driver to follow ) 
4 ddm 12 + ! C driver start block ) 
А ddm 16 + w! С driver is 10 blocks long ) 
1 ddm 18 + w! С and runs on Macintosh =1 ) 


: create.dpm 
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dpm 200 0 fill 

5453 dpm w! 

10 dpm 2+ ! С starting block of partition ) 
read.cap drop 19 - dpm 6 + ! ( # of blocks ) 
"$1 dpm А+! С TFS1 signature ) 

0 dpm E * ! 


decimal 
: read.ddm 


0 read.blk 2+ w! Ø read.blk 4 + c! 

1 read.blk 5 + c! 

120 read.blk myDisk 8 ddm 512 doscsi.r 
2drop 


: read.dpm 


0 read.blk 2* w! 1 read.blk 4 * c! 

1 read.blk 5 * c! 

120 read.blk myDisk 6 dpm 512 doscsi.r 
2drop 


: write.ddm 


0 write.blk 2+ w! Ø write.blk 4 + c! 

1 write.blk 5 + c! 

120 write.blk myDisk @ ddm 512 doscsi.w 
2drop 


: write.dpm 


0 write.blk 2* w! 1 write.blk 4 * c! 

1 write.blk 5 * c! 

120 write.blk myDisk @ dpm 512 doscsi.w 
2drop 


: get.sdrv ( | length - length ) 


(71 scsidisk dup 
xlen dup -> length driver.block swap стоуе 
length 


: write.sdrv ( length | sectors ) 


: бтр ( block | - } С for easy testing of SCSI disk contents 
) 


д 


0 write.blk 2+ w! 4 write.blk 4 + c! 
length 512 / 1+ dup write.blk 5 + c! -> sectors 
120 write.blk myDisk @ driver.block 
sectors 512 * doscsi.w 
cr .? Driver written. Stat, Mess ="... 


0 read.blk 2+ w! block? read.blk 4 + c! 
1 read.blk 5 + c! 

120 read.blk myDisk 6 ddm 512 doscsi.r 
2drop 

ddm 20 dump 


.TRAP  _ленр4г, $$ $45 1E 
$308 CONSTANT DQHeader 
6 CONSTANT QTail 


VARIABLE syshp.drvr 


: install.driver ( | dstart dlength dbytes pointer - ) 


read.ddm 

ddm 18 + @ -> dstart 

ddm 22 + w8 -> dlength 

cr .” Driver starts at sector * dstart . 

.^ and is “ dlength . .” sectors long.” 
dlength 512 * -> dbytes 

dstart 256 /mod read.blk 2+ w! read.blk 4 + c! 
dlength read.blk 5 + c! 


120 read.blk myDisk 6 driver.block dbytes doscsi.r 


cr ." Driver read; stet, mess = “ . . 
dbytes MOVE.L (А62%,00 
_newptr,sys С get memory block in system heap ) 
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MOVE.L A0,-C(A6) -> pointer 

pointer 

IF driver.block pointer dbytes cmove 
pointer syshp.drvr ! 


ELSE .^ Not enough system heap for installation.^ cr 


THEN 


CODE call.driver 


MOVE.L 05,-(САТ) 
MOVE.L (A62*,D5 
MOVE.L (A62*,A0 
execute 

MOVE.L CA7)+,D5 
RTS 


END-CODE 


: mount.scsi 


2 


install.driver 

read.dpm 

SysEvtMask 6 

0 SysEvtMask ! 

syshp.drvr 6 dpm myDisk 6 call.driver 
SysEvtMask ! 


: zero.scsi 


DQHeader qTail + 6 dQDrive + иё C drive # found ) 


cr .^ Do you want to zero the directory of drive # * 


дир. .” 7° 
yesno if “ JL’s Hard Disk” call DIZero 


cr .? Result code = “ . cr 
then 


; 
: mount 


cr .” Looking for SCSI devices..." 

get.disk 

cr .^ SCSI drive found at address ^ myDisk 6. 
cr show.cap 

cr .^ format disk? ” 

yesno IF 


cr .^ Do you REALLY want to erase this SCSI disk? ” 


yesno IF cr .^ Reformatting disk... ^ 
format 
THEN 
THEN 
modenoattn 
create.ddm create.dpm 
write.ddm write.dpm 


cr .^ Device and partition descriptor maps written. ” 


get.sdrv 

cr .“ Writing driver ... ” 
write.sdrv 

mount .scsi 

zero.scsi 


: install.men ( | dbytes pointer - } 


, 


get.sdrv 
(71 scsidisk xlen dup -? dbytes 
MOVE.L (A62*,D0 
-newptr,sys С get memory block in system heap ) 
MOVE.L A0,-CA6) -> pointer 
pointer 
IF driver.block pointer dbytes cmove 
pointer syshp.drvr ! 


ELSE .^ Not enough system heap for installation.” cr 


THEN 


: mount .mem 


install.mem 

read.dpm 

SusEvtMask 8 

0 SysEvtMask ! 

syshp.drvr 6 dpm myDisk 6 call.driver 
SysEvtMask ! 


Forth Forum 
Iime Manager Reminder DA 


Jórg Langowski is a bio-chemical engineer for a french con- 
cern and is a founding and current board member of MacTutor. 
He can be reached at EMBL, с/о I.L.L. 156x, Grenoble, Cedex, 
France F-38042. We encourage European authors to contact 
Jórg directly about submissions to MacTutor. 


"Using the Time Manager" 


One thing I always wanted to have оп my Mac is some utility 
that reminds me of an appointment, no matter what I'm doing on 
the machine at any given time. On our VAX, for example, there 
is this great program called Reminder which sits in the back- 
ground and will beep at you when your next appointment arrives. 


In the new system (128K ROMS and up) there exists a set of 
routines called the Time Manager. I thought it would be a good 
idea to show you their usage in developing a Reminder utility 
similar to the one on the VAX. In the process, I'll show you how 
to work with modeless dialogs from a DA, how to call memory 
manager dependent traps from a time manager task, and some 
more. 


The Time Manager 


The Time manager is used to execute a task at a predetermined 
time. Its routines are documented in IM Vol. 4. All time manager 
tasks are described by entries in the time mamager queue, where 
each element has the following format: 


header TMtask 14 allot 
0 CONSTANT qLink 

4 CONSTANT qType 

6 CONSTANT tmTask 
10 CONSTANT tmCount 


That means, the queue entry looks just like a regular queue 
element, with two 4-byte fields, tmTask and tmCount, relevant to 
our task. tmTask contains a pointer to the routine to be executed, 
and tmCount is used by the system to count down the elapsed 
time. When it has reached zero, the task at tmTask will be 
executed 

Three routines are provided by the time manager: InsTime, 
called with a pointer to the queue element in AQ, will insert this 
queue element into the time manager queue. PrimeTime, with the 
queue element pointer in AO and a 32-bit count in DO, will 
Schedule the routine specified in that queue element to be 
executed after count milliseconds have elapsed. RmvTime, with 
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: Reminder ===== 


Dauid, 

Don't forget to take out the trash 

and put out the cat. find while your at it, 
how about coming to bed!? 

Love, Laurą 


Reminder UtilityRS 1987 J. Langowski 


Written in Mach2™ Forth 


Fig. 1 Our Reminder DA lets Mac Widows post 
alerts for late night programmers! 


а pointer to the queue element in А0, will remove the queue 
element. The Mach2 interface to these routines is given at the 
beginning of listing 1. 


Programming the Reminder utility 


The strategy to follow seems very simple: we create a desk 
accessory that allows us to enter a message text and a delay time, 
that desk accessory will then setup a queue element with a pointer 
to a routine that displays an alert box containing that string. 

Thinking about it, programming such a utility is not quite so 
simple. First of all, the routine passed to the time manager for 
execution cannot be part of the desk accessory. We'd like to enter 
appointments that are due in several hours or days (32 bits of 
milliseconds, unsigned, give a maximum possible delay of 49.7 
days), and we’ll most probably have left the application where 
the desk accessory was started by then. Under MultiFinder this 
doesn’t matter, but under Finder, the desk accessory would have 


Ө David, 
Don't forget to take out the trash 


and put out the cat. find while your at it, 
how about coming to bed!? 
Love, Laura 


Fig.2 After time has elapsed, an alert pops up! 


© The Definitive MacTutor, Vol. 4 


been closed, leaving the task pointer point to anything but the 
desired code. 

My first thought was to use a 'stick-around' desk accessory 
that would automatically restart itself after an involuntary close, 
likeIdescribed earlier. Butitis actually much easier to put acopy 
of the routine to be executed into a small block of system heap, 
leaving it independent of the DA. Then, one has to take caution 
that the routine, once executed, will remove its own queue entry 
and dispose of its own memory. 

The second problem is that a time manager task may be 
executed at any time, interrupting whatever else is being done at 
that moment. For the same reason as in the case of VBL tasks, we 
may not call any routines from the time manager task that can 
move things around in the heap. If we did, there would be a 
chance that the interrupt occurs right in the middle of a memory 
manager operation, or while a handle hangs around dereferenced 
somewhere. 

The time manager task must therefore be rather simple. I use 
the same trick as I described for the ‘stick-around’ DA, patching 
SystemTask from the scheduled routine. The next time Syste- 
mTask is called (which should happen rather soon in any benign 
application) the patch routine will be executed, which then can do 
the more involved stuff such as drawing an alert box. 

Now look at the first part of the example: the routine that is 
executed by the time manager is contained between the markers 
mytask and mytask.end. The first bytes of this block contain the 
queue element. The name string ‘Reminder’ follows for debug- 
ging purposes. Some local variable space is reserved, where the 
original SystemTask trap address, the alert ID and the alert 
message can be kept. The SystemTask patch routine alertMe 
follows. It will display а note alert with the message in parameter 
^0, unlock the alert, remove the time manager queue element and 
dispose of the memory allocated for itself. 


alertMe is patched into SystemTask by the following routine, 
wakeMe, which is the one first executed by the time manager. A 
pointer to wakeMe will be contained in the tmTask field of the 
queue element at the beginning of the block. Since we do not 
know yet where this routine will be located, we'll have to install 
the pointer after moving the code into the system heap. 

As you see, the code between mytask and mytask.end is 
completely self-contained (as long as the ALRT resource can be 
found). We may therefore move any number of these little code 
blocksinto the system heap and install their queue elements using 
the time manager; each will be executed at its scheduled time and 
display its little message. Appointment “objects”, so to say. 


The desk accessory 


TheDA is used to install the tasks. Itisa very simple DA which 
_ Just draws up a modeless dialog box with two editable text items. 
The dialog window will have the driver reference number in its 
windowKind field, so that the system will handle mouse down 
events in the close box and drag region. Only when the event is 
passed through to the DA, windowKind will be temporarily set to 
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2 (dialog window), so that IsDialogEvent and DialogSelect work 
correctly. 

When the OK button in the dialog box has been clicked, the 
dialog handler will be invoked. This routine converts the string 
in item 4 to a number, the delay in seconds, and gets the message 
to be displayed after this delay (item 3). These parameters are 
passed to install.wakeup, together with the alert ID. 
install.wakeup gets the wakeup routine described above from 
the resource file and installs a copy of it in the system heap. It 
Saves a pointer to the wakeup routine in the tmTask field of the 
queue element, stores the alert ID and the message string at their 
appropriate positions and then schedules the routine for execu- 
tion by calling InsTime and PrimeTime. 


Things missing 


The desk accessory described here is already quite useful ‘as 
is’. However, one could include some improvements that I leave 
as an exercise for you (or me, for that matter): 

- Input of the appointment time in standard date format. 

- Keeping a list of appointments that can be displayed and 
edited. 

- Saving this list to a file every time it is changed; this file is then 
checked on system startup and the pending appointments re- 
scheduled automatically. 

I wish you good luck with those experiments; now, some mail 
that I recently received. 


Feedback Dept. 


"Dear Jörg, 

I read your recent column in MacTutor with great interest and 
would like to obtain the addresses for Serge Rostan and also for 
Winsoft. [Serge Rostan, “TechnoPro” , rue Faraday, F-78180 
Montigny le Bretonneux, France, phone (33) 1 30 45 26 62, and 
Winsoft, 34, boulevard de l'Esplanade, F-38000 Grenoble, 
France, phone (33) 76 87 56 01 - JL]. 

We are in the process of completing a book on fonts for the 
Macintosh for European and many other non-Roman languages. 
It will also show specimens of over 2000 bit-mapped and several 
hundred PostScript fonts. 

If you can suggest any font vendors that do not advertise in US 
Macintosh magazines, it would be very helpful [not off the top of 
my head, but Г ll look around - JL]. 

As you may know, Apple refuses to sell European keyboards 
in the US, even to certified developers. Users here must cultivate 
acquaintances overseas and buy them indirectly. Do you know 
whether Apple tries to prevent the export of such keyboards from 
Europe? We would like to be able to list a commercial source for 
such keyboards in our book, but do not want to cause difficulties 
for anyone there. If they are readily available for export, we 
would appreciate the name of a recommended source. 

[You address a problem that I' ve encountered myself. There 
seems no way for Macintosh developers in France to get other 
than French keyboards through the developer program. How- 
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ever, there is а least one Apple dealer in Grenoble who sells the 
US keyboard on request; we have several international research 
institutions here, so there' s a market. I' ll send you addresses of 
some Apple dealers in Germany and France that you might be 
able to order from. 

I don’ t think there are any export restrictions imposed by Apple 
on non-US keyboards into the US (unless you re-sell them to 
Colonel Kh...). The problem most probably is the bureaucracy 
that inevitably builds up in a large corporation, even one like 
Apple that for a while tried to maintain some 'non-conformistic 
hacker' kind of image. Which it is trying to forget at a rapid rate, 
I presume. Someone, it seems, must have set a guideline thar in 
country X only systems localized for X will be sold, with few 
exceptions. The only wayl get the mostrecent US system updates 
isthrough US sources, too. Funniest of all: The МасП systemthat 
I finally got a week ago (yes, I love it), has English documenta- 
tion, US system disks (but 4.1, not 4.2, which is not officially 
released at the time I write this), but no way can I get a US 
keyboard. Probably the people at Apple France just wanted to be 
nice and ship me as many US parts as possible, but then they had 
only French keyboards. What a nuisance to have all the numbers 
on the top row...] 

Lastly, Apple also tries to limit the availability of any Script 
Manager code or fonts it has developed to the country for which 
it was developed! This seems strange given that the Macintosh is 
touted as a Multinational machine. Apple has made Kanji and 
Arabic available through APDA, but feels that they are sufficient 
for the testing purposes intended. They have also developed a 
Chinese, a Hebrew and a Greek. The Chinese is distributed from 
Hong Kong and the Hebrew and Greek are distributed from Paris. 
I have written to the Paris office to no avail after a conversation 
with Mark Davis at Apple, the creator of the Script Manager. Do 
you know of a way for someone in the US to get these fonts from 
Paris? Actually, Iam more interested in finding out the arrange- 
ment of characters in the coding table than I am in the font, but 
the exact status of *dead' keys mightbe hard to discern accurately 
without actually having the font in hand. 

Best regards, 

Tim Ryan, SourceNet, Santa Barbara, CA “ 


[You address a very timely issue, that' s why I have your letter 
printed immediately without having the answers on hand yet. I'll 
forward your mail with my comments to Apple France. I'm 
actually quite optimistic that you can get the Script Manager 
versions that you want. JL] 

One comment to the letter from Peter Adamson, MT V4#1, 
p.11: The Pascal equivalent to the Mach2 PAUSE is actually 
WaitNextEvent; much like PAUSE under Mach2, WaitNextE- 
vent will transfer control to the next MultiFinder task under 
certain circumstances. If you have a very long event loop, you 
may try to intersperse WaitNextEvents with event masks of zero, 
so that they'll always return a null event. That should transfer 
control to the next task under MultiFinder. Only the crucial 
WaitNextEvent - the one with the BIG case statement behind it 
- would be called with a non-zero event mask. This is all untested, 
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so don't blame me if it doesn't work. 
See you next month. 


Listing 1: Appointment reminder using the time manager 


V ***** Time manager example - а ‘reminder’ utility 
N J. Langowski December 87 
\ 


\ Strategy: write а driver that sets up а dialog which allows 
N to enter а time & message to display after that time. After 
\ the appointment has been entered, the driver sets up а 

N time manager call for that appointment. 

N The time manager routine installs а SystemTask trap 

\ patch which at the next occasion will draw an alert box 

V containing the message to be displayed. 

A 


\ Note that we have to use the patch rether than calling 
N the alert routine directly from our time manager task, 
V since we can’t be sure we're not in the middle of a 

\ memory manager operation when it is called. 


only forth also assembler also mac 


CODE InsTime ( tmTaskPtr | - ) 
MOVE.L САб 2+, Аб 
_InsTime 
RTS 

END-CODE MACH 


CODE PrimeTime C tmTaskPtr count | - ) 
MOVE.L (Аб2%,00 
MOVE.L САб +, Аб 
-PrimeTime 


END-CODE MACH 


CODE RmvTime C tmTaskPtr | - ) 
MOVE.L (A6)*,A0 
-RnvTime 


RTS 
END-CODE MACH 


4ascii MENU constant "menu 
4ascii PROC constent "proc 


V *** compiler support words for external definitions *** 
: :xdef 
create -4 allot 
$4EFA w, C МР D 
9 w, C entry point to be filled later ) 
0, C length of routine to be filled later ) 
here 6 - 76543 


: ;xdef ( branch marker entry | - } 

marker 76543 € abort^ xdef mismatch" 
entry branch - branch w! 

here branch - 2+ branch 2* ! 


: Xlen 4 + ё; С get length word of external definition ) 
( *** driver header block *** ) 


0 CONSTANT drvrF lags 
2 CONSTANT drvrdelay 
4 CONSTANT drvrEMask 
6 CONSTANT drvrMenu 

8 CONSTANT drvrOpen 

19 CONSTANT drvrPrime 
12 CONSTANT drvrCtl 
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14 CONSTANT drvrStatus 
16 CONSTANT drvrClose 
18 CONSTANT drvrname 
50 CONSTANT DAlength 


V *** compiler support words for DA and driver definitions 
: :DA 
create -4 81104 


here 87654 ( start of DA block, and marker ) 
50 allot С length of block ) 


: ;DA ( DAstart marker Ropen Rprime Rct! Rstatus Rclose 


Rflags Rdelay Remask Rmenu Rname | - ) 
marker 87654 © abort” DA definition mismatch” 
Ropen DAStart - DAStart drvrOpen + w! 
Rprime DAStart - DAStart drvrPrime + w! 
Ret] DAStert - DAStart drvrCt] + w! 
Rstatus DAStart - DAStart drvrStatus + w! 
Rclose DAStert - DAStart drvrClose + w! 
Rf lags DAStart drvrFlags * w! 

Rde lay DAStart drvrDelay + w! 
Remask DAStart drvrEmask + w! 
RMenu DAStart drvrMenu + w! 


Rname count dup DAStart дгугМате + c! 
DAStart drvrName + 1+ swap 
dup 31 > if drop 31 then cmove 

here DAstart - DAStart DAlength + ! 


2 


: DAlen DAlength + ë ; 
\ get length word of external definition 


\ **** DA glue macros 


CODE DA.prelude 
LINK А6,8-512 \ 512 bytes of local Forth stack 
MOVEM.L A2-A1,-CAT) N save registers 
MOVE.L A6,A3 \ setup local Тоор return stack 
SUBA.L  8256,A3 \ in the low 256 local stack bytes 
MOVE.L A0,-(A6) N parameter block 
MOVE.L A1,-CA6) \ device control entry 
RTS \ just to indicate the MACHro stops here 
END-CODE MACH 


CODE DA.epi logue 
MOVE.L (A6)+,D8 X return code 
MOVEM.L CA72*,A0-A1 N restore registers 
UNLK A6 


RTS 
END-CODE MACH 


CODE DA.Jiodone 
MOVE.L (CA6)+,D8 N return code 
MOVEM.L C(A72*,A0-A1 N restore registers 
UNLK А6 
move.1 JIODone, А0 
тоует.1 d4-d7/a4-a6,-(a7) 
jsr (ай) 
movem.] (а7)+, 94-97 /а4-аб 
5 


ЕТ 
END-CODE MACH 
‚ TRAP _newptr,sys $A51E 
50000000 10 100 1010 CONSTANT DAEmask 
$ 184 CONSTANT SystemTask 
I—— Je MÁ——— P эы сы 
\ time manager and systemTask patch routine 


V this routine must reside іп а block allocated 
V in the system heap through а pointer. 
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header myTask 14 allot 
6 CONSTANT taskPtr 
HEADER myName 

DC.B 9,0, ‘Reminder ’ 
header myTrep 4 allot 
header myAlert 4 allot 
header myString 256 allot 


: alertMe 
MOVEM.L Ай-А4/А6/00-07,-СА7) 
LINK A6,®-128 X 128 bytes of local Forth stack 
(call) frontwindow windowkind + 6 
2 O IF 
[°] myTrep @ SystemTask (call) SetTrapAddress 
(71 myString 0 0 0 (call) paramText 
[^] myAlert 6 0 (call) noteAlert drop 
(71 myAlert 6 (call) freeAlert 
(71 myTask RmvTime 
[*] myTask (call) DisposPtr drop 
THEN 
UNLK A6 
MOVEM.L (А72%,Ай-А4/А6/00-07 


: wakeMe 
SystemTask (call) GetTrapAddr [’] myTrap ! 
(71 alertMe SystemTask (call) SetTrapAddr 
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header mytask.end 

' макете ” mytask - CONSTANT *wakeme \ task offset 

* myAlert ' mytesk - CONSTANT *myAlert X alertID 

' myString ' mytask - CONSTANT *myString \ alert string 


\ desk accessory code starts here. 
\ 


—la3əyes[ kn. n h Ñas cr err ee er ts SSS 


:DA reminder 
„ALIGN 


( *** main desk accessory routines *** ) 
header myRes® 4 allot \ local res 10=6 offset 
header dlgText 256 allot 


\ redefinition of cmove to make it 
\ available locally 


CODE cmove 
поуе.1 (аб)+, 90 
move.] (a6)+,a1 
моуе.1 (аб)+, ав 
tst.1 d 
bles 062 

61  move.b (а0)+,(а1)+ 
subq.] 81,40 


bne.s 61 
62 rts 
END-CODE 


\ wakeup routine installation 


: install.wekeup 
( delay alrtID msg | procHd] hSize taskBlock - ) 


“proc [^] myResQ 6 (call) GetResource -> procHdl 
procHdl (call) getHandleSize -> hSize 

hSize MOVE.L САб)+,00 

-newPtr,sys 
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MOVE.L Ай,-САб) -> taskBlock 
procHd] 6 taskBlock hSize cmove 
procHd] (call) releaseResource 
\ we have made а local copy of the wakeup routine 
teskBlock dup *wakeMe + swap taskPtr + ! 
msg taskBlock *myString + 256 cmove 
alrtID taskBlock *myAlert + ! 
alrtID (call) CouldAlert 
taskBlock InsTime 
taskBlock delay PrimeTime 
\ now the wakeup routine will wake up after 
\ the scheduled delay. 


) 


: getDrvrID ( dCtlEntry | - num } 
dCtlEntry dCtlRefNum + wê 1l. ext 
1% negate 


: ownResID ( resID drvrID ) 
5 shi + -16384 + 


: Open ( parblk асе | DAWind Res - returncode ) 
5 (call) sysbeep 
V to get attention if automatically opened 
0 dce getDrvrID ownResID -> Res 
dce dCtlWindow + @ -> DAWind 
DAWind Ø= IF C not open already 2 
Кезб ['] muRes0 ! 
Resø 0 -1 (call) getNewDialog -> DAWind 
DAWind dce dCtlWindow * ! 
N Store dialog pointer 
DAWind dce dCtlRefNum + wê 
swap windowKind * w! 
ELSE 


DAWind (call) selectWindow 
THEN 
0 


7 
: Close ( parblk асе | - returncode ) 
dce dCtlWindow + 
dup 6 (call) DisposDialog 
0 swap ! С so that Open will work again 2 
0 


: dialog-handler 
( digPtr itemHit | 
itemType hItem rBox seconds - ) 


V we get here if the OK button in the dialog 

N has been hit, therefore itemHit is always 71 
\ - in our case. But it is nice to have itemHit 
\ available, to be more generel. 

V item #3 contains the appointment message 

V item 84 contains the delay in seconds 

N (decimal number string) 


digPtr 4 ^ itemType ^ hItem ^ rBox (call) GetDItem 
hItem [^] digText (call) GetIText 
[°] digText (call) StringToNum -> seconds 
seconds Ø IF 

digPtr 3 ^ itemType ^ hItem ^ rBox 

(call) GetDItem 
hItem 171 dlgText (call) GetIText 
seconds 1000 w* 
(41 myres® 6 Г“) digText install.wekeup 
ELSE 10 (call) sysbeep 
THEN 


) 


: Ctl ( parblk асе | 
DAWind event-rec dlgPtr itemHit — returncode ) 
dce dCtlWindow + @ -> DAWind 
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parblk csCode + мё 1.ext 
CASE 
accEvent ОҒ 
2 DAWind windowKind * w! 

V set to dialog window 
parblk csParam + 6 -> event-rec 
event-rec (call) IsDialogEvent 
IF event-rec ^ dlgPtr ^ itemHit 

(call) Dialogselect 
IF digPtr itemHit dialog-handler THEN 
THEN 
DAWind dce dCtlRefNum * we 
swap windowKind * w! 
N reset windowkind 
ENDOF 


ENDCASE 
0 


: DrOpen DA.Prelude Open DA.Epilogue ; 

: ОгС1озе DA.Prelude Close DA.Epilogue ; 
: DrCt! DA.Prelude СИ DA.JioDone ; 

: DrStetus ; 

: DrPrime ; 


‘ DrOpen “ DrPrime ° DrCt] ° DrStatus ° DrClose 

$7400 X need lock, need time, need goodbye, ct! calls 
60 DAEmask @ X delay mask menu 

* Reminder^ \ name 

;DA 


С write resource to file ) 

: $create-res С str-addr - errcode ) 
call CreateResF ile 
call ResError L_ext 


7 

: $open-res ( addr | refNum - refNum or errcode ) 
addr call OpenResFile -> refNum 
call ResError L.ext 
?dup IF ELSE refNum THEN 


. close-res C refNum - errcode ) 
call CloseResFile 
call ResError L ext 


7 

: make-res ( addr len rtype ID name | - ) 
addr len call PtrToHand 
abort? Could not create resource handle" 
rtgpe ID name call AddResource 


: write-out ( filename | refnum - ) 
filename $create-res 
abort? That resource file already exists" 
filename $open-res 
dup @< abort” Open resource file failed’ 
-) refnum 
refnum call UseResF ile 
(71 reminder dup DALen 
*drvr 12 * Reminder^ make-res 
(71 myTask [“] mytask.end over - 
“proc -16000 “ wakeUp^ make-res 
“proc - 16008 call GetResource 
dup 80 call SetResAttrs 
( 64: sysheap + 16: locked ) 
call ChangedResource 
refnum close-res 
abort” Could not close resource file” 


: make-DA 
“ Reminder .г5гс” $delete drop 
* Reminder .rsrc” write-out - 


7 ‘Sell 


(42.7 229 
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Forth Forum 


Direct 68881 Floating Point Access 


Being the proud owner of a MacII since the beginning of this 
year, I was - like so many others - disappointed at the relative 
slowness of the SANE package. Even with the floating point 
coprocessor, the speedup is only a factor of 5-10 compared to the 
Mac SE. The coprocessor itself allows you to go much faster than 
that, and itis Apple's SANE implementation that slows down the 
operations. 

The reason for this is, of course, that Apple is trying to 
guarantee the *compatibility' of the SANE on the MacII with the 
old SANE implementation. That means that the results are 
supposed to be the same, down to the least significant bit (or even 
to the last guard bit?). The 68881 uses different algorithms for 
calculating transcendental functions than SANE does, therefore 
some of its built-in operations could not be used and had to be 
replaced by software. Of course, that slows down things a lot. 

AS a side note, I'm not at all in favor of such a strategy. 
Artificially restraining a high performance chip just because its 
results, although accurate enough, don't match the old - also 
accurate - results to the last bit seems a little exaggerated. Stable 
numerical algorithms should take into account the possibility that 
the hardware changes slightly and the machine errors are differ- 
ent, and they should be immune against such changes; or at least 
the new SANE should have had an option built in that uses the 
68881 directly! [Amen to that statement! -Ed] 

Many of the development systems for the Macintosh now 
come with the possibility to generate code that supports the 
floating point coprocessor directly, many others don't; working 
with Forth, we don't have a real problem since we can easily 
redefine our floating point operators. This month I'll show you 
how to do that. 

The 68881 

Let's first have a look at the floating point coprocessor itself. 

The 68881 is accessed from the 68020 in a special address 
area. When the 68020 encounters an instruction of the form 
$Fxxx (previously the F line trap), it will set its function code 
lines (pins FCO-FC2) all to high, indicating ‘CPU space’. It will 
then exchange information with the coprocessor’s internal regis- 
ters to perform the floating point operation requested. 

This information exchange occurs automatically, it is part of 
the 68020's design; when using the floating point instructions, 
you don't notice the communication between the two processors 
at all. The 68881 appears as an extension to the 68020, just as if 
we had a new set of registers available, with special instructions 
operating on them. 

The registers FPO-FP7 can each hold one extended precision 
(80-bit) floating point number, in the format given by the IEEE 
standard: bits 0-63 contain the mantissa, 64-78 the 15-bit expo- 
nent offset by 16383, and bit 79 the sign. The instruction set of 
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the 68881 allows you to do floating point operations on any or 
between any two of these registers, and transfer data between 
them, the 68020's registers and memory. 

Mach2's assembler fully supports all 68881 instructions. 
The redefinition of the words in the SANE vocabulary is there- 
fore quite straightforward. Register D7 is used by Mach2 as the 
floating point stack pointer, all we have to do is to transfer 
floating point numbers from the FP stack to the 68881's registers, 
do the FP operation and transfer back the result. 

The 68881 expects floating point numbers in a different 
format than SANE does. In order to keep FP numbers aligned to 
the boundaries of a 32-bit long word, which speeds up Operations, 
an extended precision number in memory will be 96 bits long 
instead of 80; there is a 16 bit gap between the 64-bit mantissa and 
the 16-bit sign and exponent field. Since SANE and the floating 
point stack in Mach2 use 80 bit numbers, we have to convert their 
format when we use the coprocessor. 

Listing 1 provides the macros f>2, f>1 and 1»f for this 
purpose. The general format fora binary floating point operation 
is then 


f>2 
fop.x  FPn, FPm 
bf 

where fop.x is an extended format floating point instruction 
that operates on floating point registers FPn and FPm. The 
example always uses registers FPO and ЕРІ. Unary operations 
are encoded the same way, using only ЕРО. 

In the example, I provided a new vocabulary f68881 that 
contains redefinitions of the most important SANE operations 
for the 68881. Of course, the concept can be far extended. We 
have eight registers at our disposition and can use them to 
optimize more complicated numerical algorithms, using only 
assembly language. I might give some examples how to do this 
in a later column. 

For the moment, let's content ourselves with the speed 
improvement that we have achieved so far, which is already 
remarkable. Some simple benchmarks are listed at the end of 
listing 1, and the results are given here: 

( MacII, direct 68881 access, 100000 loops each ) 

bmark12 Secs 18 Ticks ok «0» (01 

bmark2 4 Secs 48 Ticks ok «0» [0] 

bmark3 4 Secs 14 Ticks ок «0» (0) 

bmark4 4 Secs 17 Ticks ok «0» [0] 

благк5 4 Secs 14 Ticks ok «0» [9] 

( MacII, SANE w/68881, 10000 loops each ) 

smark1 15 Ticks ok «0» [0] 

smark2 37 Secs 12 Ticks ok «0» [0] 

smark3 24 Ticks ok «0» [0] 

smark4 1 Secs 33 Ticks ok «0» [9] 

smerkb 1 Secs 33 Ticks ok «0» [Ø] 


( Mac *, SANE, 10000 loops each ) 
ok «0» (01 
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smarki 24 Ticks ok «0» [Ø] 

smark2 181 Secs 54 Тіске ок «0» [0] 

smark3 49 Тіске ok <0» 101 

smark4 4 Secs 47 Ticks ок «0? [0] 

smarkb 5 Secs 14 Ticks ok (Ø> [Ø] 

For the Mac+, the тиШ апа fnull2 operations had been 
replaced by simple fdrops. As you see, the speedup going from 
Мас+ to MacII's SANE is not so breathtaking: a factor of 6 for 
the exponential, 4 for addition and subtraction; but when we 
access the 68881 directly, we gain another factor of 3 for simple 
addition and multiplication and 78 for the exponential. It is in the 
calculation of the transcendentals where the 68881 really shines. 

Pop up menus 

Someone approached me lately on the question of how to do 
pop up menu selection. Since the technical notes contain only 
sketchy references to popup menus at the time I write this (e.g. 
TN156, TN172), Га like to give you a practical example how to 
use pop up menus from Mach2 in a simple way. 

Listing 2 explains the process. The PopUpMenuSelect trap 
takes four parameters: 

- a handle to the menu to be displayed (32 bits), 

- the top and left global coordinate of the point at which to 

display the menu (2*16 bits), 

- the menu item which should be positioned at that point for 

the default selection. 

Although Mach2 knows the trap name, the interface to this 
routine is not (yet) correct, so we have to redefine it in assembler. 
Note that the point returned by the @mouse function is in local 
coordinates, while PopUpMenuSelect expects it in global coor- 
dinates. 

The example defines a menu using the Mach2 interface; the 
menu is created with -1 as the insertion parameter 
(-1 150 mymenu BOUNDS) so that after insertion into the 
tasks's menu bar the menu will stay invisible (just as we did for 
the hierarchical menus). Note that a pop up menu has to be 
inserted into the menu bar before using it. 

The content handler for the default Mach2 window is then 
rewritten sothat on a mouse down event it will select the example 
pop up menu. The menu handler will just beep a number of times 
depending on the item selected. dopop activates the new content 
handler while nopop deactivates it. 

Feedback dept. 

This letter comes from Vassili Dzuba, Paris: 

“In January’s issue ‘Mousehole Report’, Alan Dall putin his 
wish list the ability to define ‘ghost copies’ of applications. Even 
without Unix’ capability of defining links, this can be done with 
a small program using the Launch trap. This program takes only 
1K on the disk. The path name of the application to launch is 
stored in ‘STR ‘ resource 1000. It’s possible to set the creator and 
the bundle bit of the ghost to have it share the same icon as the real 
thing. Of course, double-clicking on a document can then launch 
the ghost instead of the application, but the slowing down is only 
marginal. 

The program is the following 

(using MPW’s assembler): 


INCLUDE ‘traps.a’ 
ghost MAIN 
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MOVE.W 80 -(ӨР) ; the context data (_launch parameter) 
MOVE.L #’STR *,-CSP2; ist parameter of GetResource 
MOVE.W 81000,-(ӨР); 2nd parameter of GetResource 
-GetResource; handle to string іп (SP) 
TST.L (SP); test if null handle (по resource available) 
BEQ.B exit; if null, go to exit 
MOVE.L (SP), Аб 
MOVE.L (Аб), (SP); handle dereferenced 
MOVE.L SP,A®; stack pointer in Аб 
-Launch 

exit .ExitToShe11 
END 


The resource file is something like this (using Rez format): 


include "types.r^ 

resource ‘STR “ (1000) ( 
“Sys :myDirectory : MyApp” 

); 


A ghost can be easily created using a small shell script 
(assuming the original ghost's directory being (MPW)dev) 
which sets up the string resource: 

duplicate (MPW)'dev:ghost^ (2) 

echo ‘include *types.r^^ànà 

‘resource 'à^'STR 797” (1000) ( *'(1)'^ );”д 

| rez -а -o (2) 


Assuming this script is named ‘summon’, the creation in the 
current directory of a ghost of MacPaint would be something 
like: 

summon 'sys:appli f:mac paint’ 'macpaint.Ghost' 


Sincerely yours" 
Thank you, Vassili, for this helpful little utility. 


Listing 1: direct access 68881 floating point words 
for Mach2 
X 68881 access, 9 J. Langowski/MacTutor Jan 1988 
only forth also assembler also sane 
vocabulary f6888 1 
also f68881 definitions 


code f>2 
add. 1 820 47 
поуе. 1 (1,80 
тоуе. 1 -С(ай),-(а!) ; move mantissa 
томе.1 -(að),-(a7) ; in two 32-bit chunks 
Subq.1 *%2,аї ; 16-bit gap 
move.w -(að),-(a7) ; move exponent + sign 
fnove.x (al)+,fpb ; transfer from stack to fp£ 
move.1 -(а0),-(а7) ; same for fpl... 
move.1 -Саб),-(а7) 
зуба.1  *2,a7 
move.w -(аб),-(аТ) ` 
fnove.x (а7)%,Ғр1 
add. 1 810,80 ; að points to 2nd fp stack item 
rts 
end-code mach 
code f>1 
add. 1 810,07 
поуе. 1 41,80 
move.] -(a0),-(aT) 
томе.1  -Ca0),-CaT) 
Subq.| %2,a7 
тоуе.м  -Ce0)2,-CaT) 
fnove.x (aT)+,fp0 
ris 
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end-code mach 


code bf 

fmove.x fp%,-Ca7) 

move.w (Ca/)+, (а02% 
transfer exponent + sign 

2994.1 %2,a7 ; skip16 
bit gap 

move.]  (a72*,Ca00* 
transfer mantissa 

томе. 1 (Ca/)+, (adit 2 
steps 

sub.1 810,07; adjust 
FP stack pointer 

rts 
end-code mach 


( note: f>1 or f?2 and bf 
should always occur in pairs 
since Df expects Аб to point 
to second floating point 
Stack position; this is 
assured by f>1 and f»2 ) 


code f* 
f?2 
fadd.x  fpl,fpd 
bf 
rts 
end-code 


code f- 
{›2 
fsub.x fpi, fp 
bf 
rts 
end-code 


code f / 
f>2 
fdiv.x  fpl,fp0 
bf. 
rts 
end-code 


code f* 
f>2 
fmul.x  fpi,fp0 
bf 
rts 
end-code 


code fmod 
f?2 
fmod.x Тр1,Гр0 
bf 
rts 
end-code 


code frem 
f>2 
frem.x fpi,fpo 
bf 
rts 
end-code 


code fabs 
f>1 
febs.x [рй 
Df 
rts 
end-code 


code facos 


f^1 
facos.x fpd 
bf 
rts 
end-code 


code fasin 
f^1 
fasin.x fp 
bf 


rts 
end-code 


code fatan 
f^1 
feten.x fp 
bf 
rts 
end-code 


code fatanh 
f>1 
fatanh.x Ғр0 
Df 
rts 
end-code 


code fcos 
f^1 
fcos.x fp 
bf 
rts 
end-code 


code fcosh 
f^1 
fcosh.x Грб 
bf 


rts 
end-code 


code fe*x 
f^1 
fetox.x fp 
bf 


rts 
end-code 


code fe^x-1 
f^1 
fetoxm1.x fp 
bf 
ris 
end-code 


code fgetexp 
Р] 
fgetexp.x fp 
bf 


rts 
end-code 


code fgetman 
1 
fgetexp.x fp 
bf 
rts 
end-code 


code fint 
f^1 
fint.x fpg 
bf 
rts 
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end-code 


code fintrz 
Р] 
fintrz.x Ғрй 
bf 


rts 
end-code 


code fin 
f>1 
flogn.x Грб 
bf 
rts 
end-code 


code flint! 
1 
flognpi.x fp 
bf 


rts 
end-code 


code #10910 
1 
flogi9.x Ғр0 
bf 


rts 
end-code 


code #1092 
f^1 
flog2.x fp 
bf 
rts 
end-code 


code fneg 
Р] 
fneg.x fpd 
bf 
ris 
end-code 


code fsin 
f^1 
fsin.x fp 
bf 
rts 
end-code 


code fsinh 
f>1 
fsinh.x fpd 
bf 
rts 
end-code 


code fsqrt 
f^1 
fsqrt.x fp9 
bf 
rts 
end-code 


code ftan 
f^1 
ften.x fp 
bf 
rts 
end-code 


code ftenh 
Р 1 


ftenh.x fp 
bf 
rts 

end-code 


code f 10^x 
f?1 
ftentox.x Грб 
bf 


rts 
end-code 


ftwotox.x Ғрй 
bf 
rts 

end-code 


fp 


also forth definitions 
code Ғпи111 

f>1 

bf 

rts 
end-code 


code fnul12 
f>2 
Df 
rts 
end-code 


: bmark1 counter 1.0 

100000 0 do fdup fnu111 
fdrop loop 
timer fdrop ; 


: bmark2 counter 4.3352 
100000 0 do fdup fe^x 

fdrop loop 

timer fdrop ; 


: bmark3 counter 

3.5 4.5 100000 0 do 
fover fover fnull2 fdrop loop 
timer fdrop fdrop ; 


: bmark4 counter 

3.5 4.5 100000 0 do 
fover fover f+ fdrop loop 
timer fdrop fdrop ; 


: bmark5 counter 

3.5 4.5 100000 0 do 
fover fover f* fdrop loop 
timer fdrop fdrop ; 


also sane 


: smark1 counter 

1.0 10000 0 do fdup 
fnulll fdrop loop 
timer fdrop ; 


: smark2 counter 

4.3352 10000 0 do fdup 
fe^x fdrop loop 
timer fdrop ; 


: smark3 counter 
3.5 4.5 10000 0 do fover 
fover fnull2 fdrop loop 
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timer fdrop fdrop ; 


: smark4 counter 
3.5 4.5 10000 0 do fover fover f* fdrop loop 
timer fdrop fdrop ; 


: smark5 counter 
3.5 4.5 10000 0 do fover fover f* fdrop loop 
timer fdrop fdrop ; 


Listing 2: Pop up menus 
X popup menu interface from Forth 
V € J. Lengowski/MacTutor Jan 1988 


X FUNCTION PopUpMenuSelect 

X (menu: MenuHandle; top, left, popUpItem: INTEGER): 
\ LONGINT; 

\ INLINE $4808; 


code popup С hMenu top left item? | menuID item - ) 
exg 04,87 
сіг.1 -(a7) 
моуе.1 12C€a6),-Ca7) N handle 
move.w 10(аб),-(а72 N top 
move.w 6(€a6),-Ca7) N left 
move.w 2(a6),-Ca7) N item 
adda.) #16,Аб 


_popupmenuse lect 
сіг.1 dð 
clr.1 di 


move.w Са7)+, 0 
move.w Са7)+,а1 
exg d4,a7 
поуе.! 99,-(аб) 
move.] 41,-(аб) 
rts 

end-code 


CODE @MOUSE 
SUBQ.L  #4,A6 
MOVE.L — A6,-CADD 
_GETMOUSE 
RTS 

END-CODE 


CODE unpack 
MOVE.L (A62,00 
CLR.L D1 
MOVE.W 00,01 
CLR.W DØ 
SWAP.W DØ 
MOVE.L 00,СА62 
MOVE.L D1,-CA6) 
RTS 

END-CODE MACH 


108 user taskmenubar 
152 user content-hook 


МЕМ . МЕМО myMenu 

* TestMenu^ myMenu TITLE 

-] 150 myMenu BOUNDS \ invisible menu 
* Item 1; Кеп 2; Item 3^ myMenu ITEMS 


taskmenubar 8 mymenu add 
call drewmenuber 


: beep 
?dup if 
0 do 5 call sysbeep loop 
then 


: content-hendler ( | pt - } 
@mouse -> pt 
* pt call localtoglobal 
mymenu 6 
pt unpack 
1 
popup 
beep drop 
run-content 


) 


: dopop [^] content-handler content-hook ! ; 
: nopop 171 run-content content-hook ! ; 


French Cracker Scandal - the Sequel 


Many of you might have wondered what has come out of the 
story we published in the August 1987 issue, about Faraglace, the 
guy who deprotected 4th Dimension and was supposed to pay the 
rest of his life for his ‘youthful sin’. 

The Apple Expo in Paris saw the situation evolve. In a 
discussion with Laurent Ribardiere, the author of Fourth Dimen- 
sion, it appeared that people at ACI - including himself - had 
really thought that they were on the track of an international 
pirate network. When, in fact, only three people were involved 
making business out of this and that the fourth guy - Faraglace - 
had met them by chance, not knowing what they were up to, was 
not clear to ACI. It was for that reason that the four were initially 
judged together. 

After the discussion with Laurent Ribardiere and Marylene 
Delbourg-Delphis (ACI’s president), ACI is now willing to 
separate the two cases - the cracker and the pirates - for the appeal. 
This could help clear up the issues and give Faraglace the chance 
to have a fairer judgment. We don’t know the position of the two 
other parties, Microsoft and Apple. Apple is apparently willing 
to follow ACT's lead. 

The Faraglace case has also served as a trigger for something 
more general. It has appeared to quite a few members of the Mac 
developer/user community in France that the relation between 
software authors, publishers and end users is still characterized 
by profound mutual distrust in too many cases. Developers and 
publishers assume that users pirate back and forth, and the user 
often has lost all hopes to get a reasonable service from the 
publisher, as far as upgrades, bug-free products and fulfillmentof 
expectations raised by advertising hype goes. 

The Faraglace case seemed to have been aggravated by this 
atmosphere of mutual distrust. This was heavily discussed on the 
Calvacom bulletin board, and the general feeling was that one 
should have some means of organized action to change the 
situation into one of mutual respect between the parties involved 
in software evolution. The basic idea had been stated already 
some months earlier by Philippe Chatiliez, rock musician and 
sysop of the MIDI section on the bulletin board: 

“Sure, software is intellectual property. But whatever is 
created by a user of the software, be it a written document, a 
drawing, music, another program or even a game score, 15 also 
intellectual property. Therefore the publisher has a responsibility 
towards the user to protect his/her rights just as the user has the 
responsibility to respect the author’s rights. This creates a soli- 
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darity between the parties." If you want to know more about the activities of Solidarsoft, 
It was from this idea that Solidarsoft was founded. Itisa | write to: 


non-profit association of software developers, publishers and Solidarsoft 
users which aims at improving the flow of information between 66 boulevard Exelmans 
these groups. Solidarsoft wants to promote the idea of mutual 75016 Paris, France. 
respect, trying to cut down on piratage and things like abusive 
licensing conditions or copy protection at the same time. Major bulletin board addresses: 
First activities of Solidarsoft include creating a “quality Compuserve: 71260,660. 73200,2025. 
label’ for software products and distributors, and acting as a Pan: chat. 
shareware clearinghouse, helping for instance to overcome BIX: chatchat. 
administrative difficulties that come up when a company uses a The Source: BELO10. 27 
shareware product and needs an invoice. Calvacom: Soft10. STEN 
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Forth Forum 
Formatted Text with Style 


TextEdit with Style(s) 


TextEdit has always been one of the major conveniences of 
the Macintosh. Life (as far as programming is concerned) is so 
much simpler with a standard editing package that takes care of 
line break, word wrap, text insertion, justification etc. for you, 
instead of having to write it yourself. 

One major reason why TextEdit was inadequate for e.g. 
word processing had always been that the text style was fixed for 
one text edit record, i.e. for one piece of edited text. Changing 
fonts, boldfacing, or changing the size of only one word or one 
phrase in the text was not possible. 

The new implementation of TextEdit that is described in IM 
Vol.V finally introduces this possibility. TextEdit now recog- 
nizes two types of TE records: the old one, having the same text 
style all over the text, and a new format where style information 
is associated and displayed with the text. Although contained in 
IM V, the new TextEdit traps are available (System 4.2 and later) 
on the Мас Plus as well as on the SE and МасП. 

A second inconvenience has been resolved: When working 
оп new type TE records, TECopy and TEPaste now uses the desk 
scrap (i.e. the general clipboard) for cutting/pasting directly. It is 
no more necessary to convert between the internal TE scrap and 
the desk scrap on activate/deactivate events. For old TE records, 
TECopy and TEPaste still only use the internal scrap (for com- 
patibility). 

The new text edit is not yet used very widely, but it is worth 
it. Therefore I thought it might be a good idea to show its function 
on a practical example in Mach2 Forth. It is based on the 
‘skeleton editor’ on the Mach2 demo disk, but contains a lot of 
enhancements, such as horizontal scrolling and scroll thumbs 
that work, and of course the text style support. 


The new TE record 


How does the system distinguish between the new and the 
old type TE record? 

Mostly, the structure of the new record is the same as the old 
one, with a couple of exceptions: The txSize field of a new TE 
record contains -1 (word, offset $50 from beginning of record). 
In that case, the fields txFont and txFace (offset $4A and $4C) are 
combined to hold the handle of what is called a style record, a 
structure that contains the style information associated with the 
text. Of course, the information previously contained in the 
txFont, txFace апа txSize fields - font, text face, and font size - 
is not meaningful anymore, since it may change over the length 
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of the text. 

Furthermore, the fields lineHeight and fontAscent (offset 
$18 and $1A) may now also contain -1, in which case the line 
height and ascent will be calculated individually for each line; if 
they contain positive numbers, the TErecord has fixed line height 
and ascent as before. 


The style record 


This structure contains the style information that belongs to 
the TErecord. Its layout is give in IM V-261 andT'll repeat it here 
(Pascal style): 


TYPE 

TEStyleHandle = *TEStylePtr; 
TEStylePtr = “TEStyleRec; 
TEStyleRec = RECORD 


nRuns: INTEGER; 

nStyles: INTEGER; 

styleTab: STHandle; 

]hTab: LHHandle; 

teRefCon: LONGINT; 

nullStyle: — nullSTHandle; 

runs: ARRAY [0..0] OF StyleRun 

END; 
StyleRun - RECORD 
startChar: ` INTEGER; 


styleIndex: INTEGER 
END; 


The text is characterized by a succession of style runs, 
characters of the same style in the TE record. The system knows 
where they start (startChar) and the index styleIndex of the 
corresponding style in a style table. Each style record contains 
information about how many style runs and how many different 
styles there are in the text (nruns, nStyles), and handles to the style 
and line height tables (styleTab, IhTab). teRefCon can be used 
freely by the application, and nullStyle contains а handle to the 
style table that is used when the selection is empty. 

The style table contains an entry for each different style 
encountered in the text: 


TYPE 

STHendle = ^STPtr; 

StPtr = ^TEStyleTable; 

TEStyleTable = ARRAY [9..0] ОҒ STElement; 


STElement = RECORD 


stCount : INTEGER; 
stHeight: INTEGER; 
stAscent: INTEGER; 
stFont: INTEGER; 
stFace: Style; 

stSize: INTEGER; 
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stColor: 
END; 


RGBColor; 


stCount indicates how often this style occurs in the text; the 
remaining fields indicate the text style. 

Since the line height now may differ from line to line, there 
is another table, the line-height table, which contains an entry for 
each line in the lineStarts array of the TE record. 


TYPE 

LHHandle = ^LHPtr; 

LHPtr = ^LHTable; 

LHTable = ARRAY (0..01 OF LHElement; 


LHElement = RECORD 
]hHeight: 
]hAscent : 


INTEGER; 
INTEGER; 
END; 


For each line, /hHeight and lhAscent contain the maximum 
height and ascent present in that line. 

Fortunately, you don't have to remember any of this infor- 
mation when using the new Text Edit. For straightforward text 
editing, all we need to know is that the TECopy, TECut, TEKey 
and TEDelete routines work as before, but Copy and Cut store a 
second type of scrap, ‘styl’, in the desk scrap. When you do а 
TEPaste, this information is not used and only the text is pasted 
into the edit record using the style that was present at the insertion 
point. For pasting ‘with style’, anew routine exists, TEStylPaste. 
This is one of 10 routines that are called through the new trap 
TEDispatch. This trap will look at a selector (integer) on top of 
stack and call the new text edit routines accordingly. 

Mach2 implements the new TE routines using their names 
and compiling the glue code for the dispatch routine automati- 
cally. One routine, TEStylInsert, has been left out accidentally, 
and is redefined in the example listing. Two more new traps exist: 
TEStylNew and TEGetOffset. Mach2 spells the former ‘TESty- 
leNew', so watch out for that. 

For simple use as in the example, the most important new 
routines that you have to remember are TEStylNew, TEStylPaste, 
TEGetOffset, TEGetStyle, and TESetStyle. 

TEStylNew is just like TENew, except that it creates a new 
type TE record. TEStylPaste will use the ‘styl’ information in the 
scrap, if present, for the text to be pasted. 

TEGetOffset works with both old and new type TE records 
and finds the character offset in the text corresponding to a certain 
point in the window (local coordinates). This is necessary for 
updating the font, size and style menu information after a change 
of the insertion point by a mouse click. 

TEGetStyle and TESetStyleare used to get and set style 
information at the selection of insertion point in the text. They 
work with another data structure, the TextStyle: 


ТҮРЕ TextStyle = RECORD 


tsFont: INTEGER; 
tsFace: Style; 
tsSize: INTEGER; 


tsColor: RGBColor 
END; 
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This record contains the text style information that is passed 
to/from the TE record. 

All these routines are, of course, documented in IM Vol. V. 
Examples on how to call them can be found in the program 
listing. Feel free to experiment with the other new TE routines. 

The example will create an editor window with vertical and 
horizontal scroll bars and read the first 1024 characters from a 
text file. You can use this text for playing around with different 
Style settings (using the menus I provided). Doing this, you will 
notice that the Style menu doesn’t seem to have any effect on the 
text. Fonts and font sizes may be changed, but underlining, 
boldfacing etc. seems to be impossible. However, when you set 
those text attributes for a certain selection and then click at 
different positions in the text, you will see that the Style menu 
changes appropriately, checkmarks appear and disappear in the 
right positions. Therefore I believe that the style changes are well 
recorded in the style record/style table; only the text display 
doesn’t seem to function. Is this a bug still present in the new 
TextEdit, or have I overlooked something obvious (question to 
you, the readers)? 

You see that editing multi-style text is not too difficult with 
the new TE routines, since they take care of almost everything. 
For saving and loading files, you would have to provide code that 
reads/writes the style record information together with the text, 
this also seems pretty straightforward. Printing a new style text 
edit record is a completely different ballgame, since no printing 
support exists (yet?) that is quite as extensive as the new TextE- 
dit. You would have to extract the style information for each line, 
using the style record, style and line height tables, and write the 
printing code from scratch. More difficult, but probably a good 
“exercise for the reader’. 


Bugs in the SCSI driver? 


Some remarks have been received that the SCSI code 
published in V4#1/2 was buggy, and someone seems to have 
crashed his hard disk using it. I feel sorry if application of that 
example (which was however marked ‘experimental’) should 
have caused trouble to anyone. The only excuse I have is that it 
was said that the code had been shown to work only for two types 
of disk, the Q280 and the ST225N, the only ones available to me 
for testing at that time. 

Let me point out here that we can only do our best to give 
examples of Macintosh programming, but never guarantee that 
everything works 100% and bug-free. Feel free to publish your 
comments, preferably with corrections, in MacTutor, that’s what 
we're here for. But for any example that is printed here or 
published on the source code disks, be prepared that something 
might go wrong, and especially DON’T run it from the disk that 
has your only copy of that 40-page report on it that is due in two 
days! Play it safe and use floppies that have nothing valuable on 
them. I learned my lesson when I crashed my own hard disk while 
writing the Forth example for the February article. 

I wish you good luck with this month’s example. The source 
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code disk contains two compiled versions, опе for Mac Plus/SE/ 
II, and one for Mac II only (contains 68020 code). As far as I have 
checked them, they don’t crash and work under MultiFinder. But 
you never know... 

Till next month, happy threading. 


Listing 1: Text Edit Example with Style 


\ New Text Edit example 

\ J. Langowski for Mac Tutor March 1988 

\ derived from 

\ Editor Shel] Example Program on Mach 2 demo disk 


\ found two ‘features’ of the new text edit while 

N experimenting: 

а. when the insertion point is at а boundary between 
two different styles, the text typed will be TEKeyed 
according to the style BEFORE the insertion point, 
while TEGetStyle will return style information from 
AFTER the insertion point. 

b. Although the text face seems to be set inside the style V 

ecord and properly associated with the text 
(TEGetStyle returns the correct information after the 
text face has been changed), the text is always drawn 
plain text style. The font and size changes work OK. 


A 0) Б” өт өт т т Шет 


only forth definitions 
8150 assembler also mac 


N ***** constants 


300 CONSTANT APPLEID 
310 CONSTANT FILEID 
320 CONSTANT EDITID 
330 CONSTANT SIZEID 
340 CONSTANT FontID 
350 CONSTANT StyleID 


20 CONSTANT InUpArrow 
21 CONSTANT InDownArrow 
22 CONSTANT InPageUp 

23 CONSTANT InPageDown 
129 CONSTANT InThumb 


$44525652 Constant “drvr 
$464F4E54 Constant “font 


%00000 1000000000 CONSTANT Shif tMask 


$10 CONSTANT portRect \ Grafport rectangle 
$6E CONSTANT wVisible \ visible flag [byte] 


\ text edit equates 

Ø CONSTANT teDestRect 

8 CONSTANT teViewRect 

$C CONSTANT selRect 

$18 CONSTANT teLineHite 

$1A CONSTANT teFontAscent 

$1C CONSTANT teSelPoint 

$20 CONSTANT teSelStart 

$22 CONSTANT teSelEnd 

$38 CONSTANT teCar0n 

$39 CONSTANT teCarAct 

$3C CONSTANT teLength 

$3E CONSTANT teTextH 

$48 CONSTANT teCROnly 

ША CONSTANT teFont 

$4C CONSTANT teFace 

$44 CONSTANT teStylHandle 
\ handle to style record for new 
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N text edit. Never accessed directly 
$4E CONSTANT teMode V text mode [word] 
$50 CONSTANT teSize N font size [word] 
\ teFont, teFace, teMode, teSize аге only 
N meaningful for old style TE records. 
\ Гог а new style record, teSize contains -1. 
V in that case, teFont and teFace together contain 
\ the handle to the style record. 
$5Е CONSTANT teNLines 
$60 CONSTANT teLines 


$480 CONSTANT TEScrpLength 
$AB4 CONSTANT TEScrpHandle 


\ Event Record Equates 
$0 CONSTANT What 
$2 CONSTANT Message 


( event code [word] 2 

( event message [long] 2 

$6 CONSTANT When ( ticks since start-up [long] ) 
$A CONSTANT Where ( mouse loc. pt. global [long] 2 
$E CONSTANT Modifiers C modifier flags [word] ) 


0А CONSTANT LF 
$26 CONSTANT SP 


( ascii 'linefeed^ ) 
( ascii ‘space’ ) 


create applestring 01 C, $14 C, \ Apple symbol 


V ***** variables 


VARIABLE TEHandle C handle for text edit record ) 
VARIABLE TERect 4 VALLOT 
( Text Edit view rectangle ) 
VARIABLE SIZE C item of current textsize ) 
VARIABLE DESKNAME 252 VALLOT \ holds name of desk accessory 
VARIABLE FONTNAME 252 VALLOT \ holds font name selected 
VARIABLE ITEMNAME 60 VALLOT 
\ receives menu item name 
VARIABLE MyStyle 8 VALLOT 
V text style record for our private use 
V fields of MyStyle: 
8 CONSTANT tsFont 
2 CONSTANT tsFace 
4 CONSTANT tsSize 
6 CONSTANT RGBColor 
VARIABLE currentFont X menu ID of font in use 
VARIABLE *fonts V 8 of currently installed fonts 
VARIABLE currentSize \ menu ID of size in use 


76 USER AbortHook 

152 USER ContentHook 

160 USER GrowHook 

164 USER CloseBoxHook 

168 USER UpdateHook 

172 USER ActivateHook 

202 USER CAction V control action routine vector 


V ***** glue routines for new text edit 


\ 

V TEStylNew С destRect viewRect - TEHandle ) 

V is misspelled ‘TEStyleNew’ in the Mach2 trap definitions, 
N but implemented. So are TEGetOffset end most of the 

\ other new text edit routines that are called through 

V TEDispatch. 

N One exception is TEStylInsert, which we are defining 

N here: 


CODE TEStylInsert С text length hST hTE — ) 
ЕХб 04,А7 
MOVE.L $CCA6),-CA7) \ pointer to text 
MOVE.L $8(A60,-CAT) \ length of text 
MOVE.L $4(460,-CAT) \ style record handle 
MOVE.L (Аб),-(АТ) \ TE record handle 
ADDA .W 8%10,А6 
MOVE .W 8%7,-САТ) 
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-TEDispatch 

ЕХО D4, AT 

RTS 
END-CODE 


V ***** windows, menus, controls, tasks etc. ***** 


NEW. WINDOW Editor 

* Editor” Editor TITLE 

42 4 330 507 Editor BOUNDS 

DOCUMENT INVISIBLE CLOSEBOX GROWBOX 
Editor ITEMS 


200 1000 TERMINAL EditTask 


NEW.MBAR EditBar 


МЕМ МЕМ) AppleMenu 

APPLESTRING AppleMenu TITLE 

0 APPLEID AppleMenu BOUNDS 

“ About Editor ...;(-” AppleMenu ITEMS 


NEW.MENU FileMenu 
“ File” FileMenu TITLE 
0 FileID FileMenu BOUNDS 
* New/N;Open.../0;Close;Save;Save as...;Revert to 
Original; (Ргіп(” 
FileMenu ITEMS 


NEW.MENU EditMenu 

“ Edit” EditMenu TITLE 

® EDITID EditMenu BOUNDS 

* (Undo/Z;(-;Cut/K;Copy/C;Paste/V;Clear” 
EditMenu ITEMS 


NEW.MENU FontMenu 

* Font? FontMenu TITLE 

8 FontID FontMenu BOUNDS 

“ (Fonts<I;(-? FontMenu ITEMS 


NEW.MENU SizeMenu 
* Size” SizeMenu TITLE 
0 SizeID SizeMenu BOUNDS 


“ 9 Point; 16 Point; 12 Point; 14 Point; 18 Point; 20 Point; 


24 Point” 
SizeMenu ITEMS 


CREATE SizeIDTable 

0, в, бс, \ по menu IDs for sizes 0 thru 8 
1 с, 2 с, дс, Зс, \ 9,10,-,12 

0 с, 4с, бс, Oc, \ -,14,-,- 

0 с, 5 с, Вс, 6c, V-,18,-,20 

0 с, 9c, Oc, Тс, \-,-,-,24 


CREATE SizeTable 
Øc, 9с, 10 с, 12c, 14c, 18 c, 20 c, 24 с, 


NEW.MENU StyleMenu 
* Style^ StyleMenu TITLE 
0 StyleID StyleMenu BOUNDS 
* Plain/P; Bold/B<B; Italic/I«I; Underline/U<U; Outline<0; 
Shadow«S; Condense; Extend” 
StyleMenu ITEMS 


NEW.CONTROL Scroll 

VSCROLLBAR VISIBLE 100 0 Scroll ITEMS 
VARIABLE lastVs 

400 CONSTANT maxVs 


NEW.CONTROL Һ5сго11 


HSCROLLBAR VISIBLE 100 8 hScroll ITEMS 
VARIABLE lastHs 
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100 CONSTANT maxHs 


: CHECK € menuhandle item flag - ) С checking а menu item ) 


CALL CheckItem ; 


: =string ( eStr bStr | - flag ) 


4 


aStr count 65536 * bStr count rot + swap 
call CmpString 0- 


CODE @TEHandle 


MOVE .L TEHandle, -CA6) RTS 
END-CODE 
: Shift? C - f) N checks the event record to see if the 


V shift key was pressed. 
EVENT-RECORD Modifiers * W8 ShiftMask AND 
IF -1 ELSE 0 THEN 


: edjustFontMenu 
\ edjust font menu and currentFont variable 


myStyle wê С font ID ) fontName call де{Епате 
8fonts ё 0 DO 
fontMenu @ i itemName call GetItem 
itemName fontName -string 
IF FontMenu 6 currentFont 6 Ø check 
\ uncheck previous font selection 
FontMenu 6 i -1 check 
i currentFont ! 


: edjustStyleMenu ( | face - ) 


2 


myStyle tsFace + w@ -> face 

8 0 00 
1 i scale face end ( get style bit ) 
if -1 else 0 then 
styleMenu 6 i 2* rot check 

LOOP 


: edjustSizeMenu 


9 


д 


SizeMenu 6 currentSize 6 Ø check 
myStyle tsSize + w@ ( size ) 
SizeIDTable + сё C sizeID ) 

dup currentSize ! 

SizeMenu @ swap -1 check 


getCurrentStyle ( | LHite FAsc - ) 
С updates variable currentFont ) 
С size and Face kept in myStyle ) 
( LHite and FAsc are currently not used ) 


@TEHandle @ teselStart + wé 

\ get start of selection Cor insertion point) 
С offset 2 myStyle ^ LHite ^ FAsc @TEHandle 

call TEGetStyle 


adjustFontMenu 
adjustStyleMenu 
adjustSizeMenu 


AdjustTERect 
\ adjust terect size for the presence of scrollbars 
portRect Editor + 4 + № ( get bottom coord ) 
16 - С subtract 16 for height of scrollbar ) 
teViewRect @TEHandle @ + 4 + W! \ store new coord back 
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іп text edit record 
: SetScrollLimits 


portRect Editor + 6 + № С get right coord ) Scroll 6 Ø CALL SetMinCtl 
16 - С subtract 16 for width of scrollbar ) Scroll ё maxVs CALL SetMaxCt1 
teViewRect @TEHandle @ + 6 + W! Scroll ё Ø CALL SetCtlValue 
: 0 lastVs ! 
hScroll ё Ø CALL SetMinCtl 
: Visible? С - Г ) \ checks visible flag in window record hScroll 6 maxHs CALL SetMaxCt] 
Editor wVisible + Сё hScroll 6 Ø CALL SetCtiValue 
j 0 lastHs ! 
V ***** event handlers ***** 
: ACTIVATE-HANDLER : EditFile ( | cher exitflag - ) 
RUN-ACTIVATE BEGIN 
EVENT-RECORD Modifiers + № С get modifiers word ) Visible? 
1 AND IF IF 
@TEHandle CALL TEActivate ?TERMINAL IF 
getCurrentStyle KEY -> char С get the character ) 
ELSE char 14 = IF 
eTEHendle CALL TEDeactivate 0 -> exitflag C if cmd '.^ exit ) 
THEN ELSE 
; char @TEHandle CALL TEKey 
( else insert ) 
1 -> exitflag С char ) 
: UPDATE-HANDLER THEN 
Editor CALL SetPort ELSE 
AdjustTERect 1-» exitflag 
Editor CALL BeginUpdate ( if no key pressed, keep looping ) 
Editor CALL DrawControls THEN 
Editor CALL DrewGrowIcon 
Editor portRect + @TEHandle CALL TEUpdate ELSE 
Editor CALL EndUpdate Q -> exitflag 
; С if window’s been closed, exit ) 
THEN 
: CONTENT-HANOLER ( | theMouse - ) exitflag € check exit condition ) 
RUN-CONTENT WHILE 
Editor CALL SetPort eTEHandle CALL TEIdle 
REPEAT 
^ theMouse CALL GetMouse р 
theMouse @TEHandle 6 TEViewRect + 
call PtInRect 
IF : Open 
theMouse Shift? @TEHandle CALL TEClick Pop-U 
getCurrentStyle Editor CALL SetPort 
THEN 
F TERect TERect CALL TEStyleNew TEHandle ! 
\ get new style TE record 
: CLOSEBOX-HANDLER -1 teCROnly @TEHANDLE ё + W! ( по word wrap ) 
Editor \ windowpointer -1 teCarAct @TEHandle @ + C! ( activate caret ) 
EVENT-RECORD Where + @ call TrackGoAwauIF Editor CALL -1 @TEHandle call TEAutoView 
HideWindow THEN N enable auto scroll 


; ( get the first 1K of text ) 


0 VIRTUAL 1024 Ø eTEHendle TEStylinsert 
V **** main editor example code ***** 0 0 eTEHandle CALL TESetSelect 


15 € doAll 2 myStyle -1 С redraw) @TEHandle 


: POP-UP call TESetStyle 
Editor CALL ShowWindow adjustFontMenu 
Editor CALL SelectWindow edjustStyleMenu 
EditBar 6 CALL SetMenuBar ad justSizeMenu 
CALL DrawMenuBar 
; AdjustTERect ( initialize the text ) 
PortRect Editor + @TEHandle CALL TEUpdate 
: ShutDown eTEHandle CALL TEDeactivate 
Editor CALL HideWindow @TEHandle CALL TEActivate 
PAUSE C PAUSE so that the i/o task can 
have а turn and handle the SetScrollLimits 
deactivate event generated by Editor CALL DrewControls Editor CALL DrewGrowIcon 
the closing of the window ) 
MACH.MBAR ( MACH menubar back on screen ) (71 UPDATE-HANDLER UpdateHook ! 
@TEHandle CALL TEDispose [*] CONTENT-HANDLER ContentHook ! 
; [^] ACTIVATE-HANDLER ActivateHook ! 
478 
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[°] CLOSEBOX-HANDLER CloseBoxHook ! 


V ***** menu handlers ***** 


: HandleDeskAcc C item? - 2) 


APPLEMENU 6 SWAP DESKNAME CALL GETITEM 


DESKNAME CALL OPENDESKACC 


DROP 


: DO-APPLE € item? - ) 


dup 


1 = IF 
( AboutEdit ) 


drop 


ELSE 
THEN 


HandleDeskAcc 


: NewFile ; 

: OpenFile ; 
: CloseFile ; 
: SaveF 11е ; 
: ЗауеАз ; 

: Revert ; 


: DO-FILE € item# - ) 


CASE 
1 OF 
2 OF 
3 OF 
4 ОҒ 
5 OF 
6 OF 
ENDC 


4 


: DO-ED 
CASE 
1 OF 
3 OF 
4 OF 
5 OF 
6 OF 
ENDC 


7 


: DO-Font ( item | fontID - ) 
FontMenu ё item? Fontname call getitem 
Fontname ^ fontID call getFNum 


NewF ile 

OpenFile 

CloseFile 

SaveFile 

SaveAs 

Revert 
ASE 


IT С item? - ) 
С TEUndo ) 


( About Editor ... 


ENDOF 
ENDOF 
ENDOF 
ENDOF 
ENDOF 
ENDOF 


ENDOF 


eTEHandle CALL TECutENDOF 

eTEHandle CALL TECopy  ENDOF 
eTEHandle CALL TEStylPaste ENDOF 
eTEHandle CALL TEDelete ENDOF 


ASE 


^ fontID w8 myStyle w! 


V put into tsFont field of style record 
1 € doFont) myStyle -1 С redraw) @TEHandle 


call TESetStyle 
FontMenu 6 currentFont 6 0 check 


FontMenu 6 item? -1 check 


item® currentFont ! 


: Do-Style ( item | facefield - ) 


myStyle tsFace + -> facef ield 


item* CASE 
1 ОҒ € plain text ) 


0 facefield w! 


ENDOF 


facefield w8 
1 item 2- scale xor 


facefield и! \ flip bit 


ENDCASE 


2 € doFace) myStyle -1 ( redraw) @TEHandle 
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) 


call TESetStyle 
adjustStyleMenu 


: Do-Size € item8 - ) 
SizeTable * ce 
myStyle tsSize + w! 
4 С doSize) myStyle -1 С redraw) @TEHandle 
call TESetStyle 
adjustS izeMenu 


7 


: MBAR-HANDLER € item? пеп 10 - ) 
CASE 
APPLEID OF DO-APPLE ENDOF 
FILEID OF DO-FILE | ENDOF 


EDITID OF DO-EDIT ENDOF 
FontID OF DO-Font ENDOF 
SIZEID OF DO-Size ENDOF 
STYLEID ОҒ DO-Style ENDOF 
ENDCASE 


0 CALL HILITEMENU 


V ***** contro] action routines ***** 


\ А control ection routine specifies what action should take 
\ place WHILE а control is being held down. 


: ScrollText (dv dh - 
dh dv eTEHandle CALL TEScro11 


9 


: 00-5сго11 ( part-code | ctlvelue - } 
pert-code 
CASE 
inuparrow OF Scroll 6 CALL GetCtlValue -> ctlvalue 
ctlvalue 0= NOT 
IF 
Scroll 6 ctlvalue 1- call SetCtlValue 
50 ScrollText 
THEN 
ENDOF 


indownarrow OF Scroll 6 call GetCtlValue -> ctlvalue 
ctlvalue maxVs = NOT 

IF 

Scroll 6 ctlvalue 1* call SetCtlValue 

-5 0 ScrollText 


inpageup OF Scroll 6 call GetCtlValue -> ctlvalue 
ctlvalue 0= NOT 

IF 

Scroll 8 ctlvalue 5 - call SetCtlValue 

25 0 ScrollText 

THEN 
ENDOF 


inpagedown OF Scroll 6 call GetCtlValue -> ctlvalue 
ctlvalue maxVs = NOT 
IF 
Scroll 69 ctlvalue 5 + call SetCtlValue 
-25 Ø ScrollText 


Scroll 6 call GetCtlValue lastVs ! 
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00-Н$сго11 ( pert-code | ctlvalue - ) 
pert-code 
CASE 


inuparrow OF hScroll @ call GetCtlValue -> ctivalue 


ctlvalue 0= NOT 
IF 
hScroll 6 ctlvalue 1- call SetCt1lValue 
0 5 ScrollText 
THEN 
ENDOF 


indownarrow OF hScroll 6 call GetCtlValue -> ctlvalue 


ctlvalue maxHs = NOT 
IF 


hScroll 6 ctlvalue 1+ call SetCt Value 
0 -5 ScrollText 


inpageup OF hScroll 8 call GetCtlValue -> ctlvalue 


ctlvalue ð= NOT 
IF 
hScroll 6  ctivalue 5 - call SetCtlValue 
0 25 ScrollText 
THEN 
ENDOF 


inpagedown OF hScroll 6 call GetCtlValue -> ctivalue 


ctlvalue maxHs = NOT 
IF 


hScroll ё ctlvalue 5 + call SetCtlValue 
0 -25 ScrollText 
THEN 
ENDOF 
ENDCASE 
hScroll 6 call GetCtlValue lestHs ! 


: ControlAction С part-code control-handle - 2 
CASE 


Scroll @ ОҒ DO-Scroll ENDOF 
hScroll 6 OF DO-hScroll ENOOF 
swap drop 

ENDCASE 


X ***** scrollbar thumb control handler ***** 


: DO-vThumb ( | ctiV ) 


inThumb = IF 

scroll 6 call getCtlValue -> с \ 
lastVs 6 ctlV - 5 * Ø scrollText 
ctlV lastVs ! 

THEN 


: DO-hThumb ( | су } 


9 


inThumb = IF 

hscroll 6 call getCtlValue -> сау 
0 lestHs 8 ctlV - 5 * scrollText 
ctlV lestHs ! 

THEN 


ControlHandler С part-code control-handle - 
CASE 
Scroll 6 OF DO-vThumb ENDOF 
hScroll 6 OF DO-hThumb  ENDOF 
swap drop 
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) 


ЕМОСАЗЕ 


\ *****. initialization ***** 


: INIT-MBAR 
EditBar ADD 
EditBar APPLEMENU ADD 


APPLEMENU 6 “drvr call addresmenu 


EditBar FileMenu ADD 
EditBar EditMenu ADD 
EditBar FontMenu ADD 


Fontmenu 8 “font call addresmenu 
Fontmenu 6 call countMItems "fonts ! 


EditBar SizeMenu ADD 
EditBar StyleMenu ADD 


) 


: INIT-TASK 


Editor ADD ( маке the Editor window ) 
Editor Scroll ADD С add vertical scroll Баг ) 
Editor hScroll ADD С add horizontal scroll bar ) 


Editor EditTesk BUILD 


д 


: START-TASK 
ACTIVATE 


(71 ControlAction CAction ! 
(^) ControlHandler Control-Vector ! 
(41 MBAR-HANDLER MENU-VECTOR ! 


BEGIN 
STANDARD-GETF ILE 
IF 


Open 

EditFile 

ShutDown 
THEN 


(71 RUN-UPDATE UpdateHook ! 

[^] RUN-CONTENT ContentHook ! 

(41 RUN-ACTIVATE ActivateHook ! 

(71 RUN-CLOSEBOX CloseBoxHook ! 

SLEEP STATUS W! С put Editor task to sleep ) 
PAUSE ( exit this task ) 


AGAIN 


: INIT-EDIT 
INIT-TASK 
INIT-MBAR 


EditBar EditTask MBAR) TASK 4 myStyle w! N default font, 


Monaco 


0 myStyle 2+ w! \ default face, plain text 
9 myStyle 4 + w! N default size, 9 point 
0 myStyle 6 +! N RGBcolor =... 


0 myStyle 10 + ж! N . 
4  TERect W! 

4 TERect 2+ W! 

288 TERect 4 + W! 

503 TERect 6 + W! 
EditTask START-TASK 


. .black 


( define the text edit rectangle ) 


: EDIT ( wakes up Editor task ) 


EDITTASK 6 


IF WAKE STATUS TASK-» EditTask W! 


ELSE INIT-EDIT 
THEN 
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Forth Forum 
Graf3D Library Access 


Graf3D and Mach? - accessing external libraries 


The subject of this month has been initiated by one of our 
readers, Paul Thomas, who in a desperate mood sent me both a 
paper letter and GEnie mail, because he needed to know whether 
it would be possible at all to access the Graf3D routines from 
Mach2. 

A little background for those who weren't with the Mac (or 
with us, for that matter) from the beginning: Graf3D is a set of 
routines on top of QuickDraw, which enable to create a 3-d 
GrafPort with all necessary support to do 3-dimensional perspec- 
tive drawing. The routines aren't explained in Inside Macintosh, 
but in several other different documents, one of them being the 
MPW Pascal manual (Appendix J). 

Graf3D was also part of the Lisa Workshop, and one of the 
first Macintosh demo programs, Boxes, used those routines. The 
Boxes program - many of you might have seen it - draws at 
random fifteen rectangular boxes on a plane and displays them in 
a 3-d perspective view. The program is written originally in Lisa 
Pascal, and also contained on the TML Pascal disk as an example. 
Listing 4 shows the original program. 

Glancing through the code, you might notice that this ex- 
ample certainly wouldn't please the User Interface Thought 
Police today. Using the whole screen as a GrafPort without 
regard to anything else on there is a definite no-no in the days of 
Multifinder, and if you run the example under Multifinder, you 
won't find your windows back on the screen afterwards because 
they are all covered by little boxes. Nevertheless, it is a nice 
example for the use of Graf3D, and we'll show you this month 
how to translate it into Mach2 (We'll also correct the garbled 
screen problem under Multifinder). 

First and most difficult question: How can we access rou- 
tines from Forth that are clearly labeled (Not in ROM) in the 
documentation? This remark tells us, of course, that they are part 
of some object library, no source code available and inaccessible 
to the Forth user. Just like the printing manager was before it was 
implemented in the Mach2 and MacForth systems. 

There may be other libraries to come, also not in ROM, and 
waiting for updates takes a long time. бо ГІ give you two general 
strategies to get access to object library code from Forth, making 
you independent of those updates. 

The first scheme I thought up was simply to write a short 
Pascal program that calls all the routines at least once - so that 
they will be loaded -, compile that program, create a linker map 
if possible, and pass the final application through Nosy. That will 
get you a more or less annotated assembly listing from which you 
can extract the source code of the not in ROM routines that you 
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are interested in. 

Well, that works for you and me on our respective desks, but 
we certainly cannot publish reverse-engineered Apple source 
code in MacTutor, at least if we want to stay in business. Also, it 
is a lot of work (i.e. translating to a different assembler dialect, 
writing the glue code, etc.), and all in all qualifies as a master 
example of a dirty hack. 

There is an easier way to go, and much more general, too: 
write some sort of a linker for Pascal library code. We write an 
assembly main program (Listing 2), which is just a table of JMP 
instructions to the routines that we want to call, and let the MPW 
linker do its job (listing 3). 

The assembly/link script will create a new resource, gr3D, 
which contains the jump instructions at the beginning, followed 
by the linked Graf3D code. All we have to do now is to provide 
a block of memory in our Forth code where this resource can be 
copied to. 

In order to assign Forth words to the JMP instructions, we 
simply make a table of CREATES, which will allocate 4 bytes to 
each name (the length of a JMP d(PC) instruction), and create a 
dictionary entry so that we know the routine's address in the jump 
table. After the block of CREATEs, we allocate sufficient 
memory So that the gr3D resource can be loaded (see listing 1). 

We write a word, Init3D, that gets the gr3D resource and 
copies itinto the table, starting with the address of the first Graf3d 
word, gInitGrf3D. Now the Graf3D routines are all set up for use 
by Mach2. As simple as that. 

Well, not quite. We still need to write glue code to move the 
parameters from the Forth stack (A6) to the Pascal stack (A7). 
That glue code is rather simple and is just the same as is used for 
calling toolbox ROM routines. Like the traps, the Graf3D code 
preserves all registers that are vital to Mach2 (A2-A7, 24-07). 
Like in the case of traps, we have to make A7 point to the lowest 
stack (EXG D4,A7) in order to avoid overwriting of Mach2 space 
by the intermediate Quickdraw record that is put between the 
stack and the heap. The glue code for the different Graf3D 
routines is given at the beginning of listing 1. 

The Boxes examples should be self-explanatory when you 
compare it with the Pascal code; in fact, it might help some of you 
Pascal programmers and casual Forth readers appreciate that 
there is really no big difference between Forth and Pascal code... 

I should point out some more things. First, the ‘access 
words’ for fields in a record, .x, .y, .pt1, and so on, defined at the 
beginning of the Forth code. Second, the word restore.screen, 
which cleans up the display after the example has run; very 
important when running under Multifinder. It basically does a 
PaintBehind(FrontWindow, grayRgn), the same mechanism by 
which many screen savers restore a blacked-out screen. Third, we 
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define a terminal task that runs the Boxes example; that way, we 
can simply check for ?terminal after each drawing loop to see 
whether we're done. Again, we have to make sure (like always in 
Mach2 multitasking) that the correct GrafPort is set by calling 
myPort3D SetPort3D before each passage through the loop. 
This is because any PAUSE-containing word, such as ?termi- 
nal, may change the active GrafPort. 

For using the example, you will first have to create the 
Graf3D glue resource file with the gr3D resource in it, then move 
that resource into the MACH.RSRC file before starting your 
Mach2 system. In case you don't have access to MPW, the source 
code disk contains the Graf3D glue and MACH.RSRC files. The 
complete program, of course, is also on the disk. 

That's it for this month; next month I plan to discuss various 
projects of object-oriented extensions to Mach2 that have re- 
cently appeared on the networks. Some of you might also 
appreciate that NEON hasn't died altogether, but that there is at 


least one person trying to extend it in a very interesting way. 
Listing 1: The Boxes example in Mach2 


N Graf3d / Mach2 glue code 
\ An example for calling MPW routines from Forth 
V J. Langowski April 1988 


\ 
Only Forth Also Mac Also Assembler 


N some general definitions first 
16 CONSTANT portRect 


GLOBAL 
CODE SCALE 

MOVE.L — (A60*,D0 
BMI.S e1 
MOVE.L . (462,01 
ASL.L 00,01 
MOVE.L 01, (Аб) 
ЕТ5 

61 MOVE.L  (A62,D1 
NEC.L 00 
ASR.L 00,01 
MOVE.L 01,(А6) 
ЕТ5 

END-CODE 

global 

CODE white 


MOVE.L (A52,-CA6) 
SUBQ.L #8, (Аб) 
RTS 

END-CODE MACH 


global 

CODE black 
MOVE.L (A52,-(A6) 
SUBI.L #16, (Аб) 


END-CODE MACH 


global 

CODE gray 
MOVE.L CA5),-CA6) 
SUBI.L #24, (Аб) 
RTS 

END-CODE MACH 


: 4ASCII 
0 
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4000 
8 SCALE Ø WORD 1+ Ce + 
LOOP 


д 


4ASCII 0730 CONSTANT “030 \ resource ID 
N Graf3D jump table 


CREATE gInitGrf3D 
CREATE gOpen3DPort 
CREATE gSetPor t3D 
CREATE gGetPor t3D 
CREATE gMoveTo2D 
CREATE gMoveTo3D 
CREATE gL ineTo2D 
CREATE gLineTo3D 
CREATE gMove2D 
CREATE gMove3D 
CREATE gL іпе20 
CREATE ді ine3D 
CREATE gViewPort 
CREATE gLookAt 
CREATE gViewAngle 
CREATE gIdent ity 
CREATE gScale 
CREATE gTranslate 
CREATE gP i tch 
CREATE gYew 
CREATE gRo11 
CREATE gSkew 
CREATE gTrensform 
CREATE gC1ip3D 
CREATE gSetPt3D 
CREATE gSetPt2D 


V The glue code is 2636 bytes long, so we allocate 
V sufficient additional buffer space to put it into 
2600 ALLOT 


: Init3D \ gets Graf3D code from gr3D=1 resource 
\ and copies it into buffer 
*gr3D 1 call GetResource 
dup @ swap call SizeRsrc 
(71 gInitGrf3D swap cmove 


7 


CODE InitGrf3d 
EXGD4,A7 
MOVE.L CA6)+,-CA7) 
JSRgInitGrf3d 
EXGD4,A7 
RTS 

END-CODE 


С globalPtr - ) 


CODE Open3DPort 
EXGD4,A7 
MOVE.L CA6)+,-CAT) 
JSR gOpen3DPor t 
EXGD4,A7 
RTS 

END-CODE 


С port - 2 


CODE SetPort3d 
EXGD4,A7 
MOVE.L CA62*,-CA7) 
JSR gSetPor t3d 
EXGD4,A7 
RTS 

END-CODE 


С port - ) 


CODE GetPort3d 
EXGD4,A7 
MOVE.L CA62*,-CAT) 


C VAR port - ) 
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JSR gGetPor t3d 
EXGD4,A7 
RTS 

END-CODE 


CODE MoveTo2d( x y - ) 
EXGD4,A7 
MOVE.L 4CA62, -CATD 
MOVE.L CA6),-CA7) 
ADDA .W #8, Аб 
JSR gMoveTo2d 
EXGD4,A7 
RTS 

END-CODE 


CODE MoveTo3d( x yz - D 
EXGD4,A7 
MOVE.L 8CA62,-CA7) 
MOVE.L 4CA6),-CA7) 
MOVE.L САб ),-САТ) 
ADDA .W #12, A6 
JSR gMoveTo3d 
EXGD4,A7 
RTS 

END-CODE 


CODE LineTo2d( x y - ) 
EXGD4,A7 
MOVE.L 4(A6),-(A7) 
MOVE.L (A62,-CAT) 
ADDA .W #8, AG 
USRgL ineTo2d 
EXGD4,A7 
RTS 


END-CODE 


CODE LineTo3d( x yz - ) 
EXGD4,A7 
MOVE.L 8САб ), -САТ) 
MOVE.L 4(Аб), САТ) 
MOVE.L САб 2, -САТ) 
ADDA .W #12, Аб 
JSRgL ineTo3d 
EXGD4,A7 
RTS 

END-CODE 


CODE Move2d С dx dy - D 
EXGD4,A7 
MOVE.L 4САб),-САТ) 
MOVE.L CA62,-CAT) 
ADDA.W #8, A6 
JSR gMove2d 
EXGD4,A7 
RTS 

END-CODE 


CODE Move3d С dx dy dz - ) 


EXGD4,A7 
MOVE.L 8СА62,-СА7) 
MOVE.L 4C€A6),-CA7) 
MOVE.L CA62,-CA7T) 
ADDA .W #12, Аб 
JSR gMove3d 
EXGD4, A7 
RTS 

END-CODE 


CODE Line2d С xy - D 
EXGD4,A7 
MOVE.L 4CA62, -CAT) 
MOVE.L CA62,-CA7T) 
ADDA.W 88, A6 
JSR gL ine2d 
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EXGD4,A7 
RTS 
END-CODE 


CODE LineSd Cx yz-) 
EXGD4,A7 
MOVE.L 8CA62,-CA7) 
MOVE.L 4CA6),-CA7) 
MOVE.L CA6),-CAT) 
ADDA.W #12, Аб 
JSR gL ine3d 
EXGD4,A7 
RTS 

END-CODE 


CODE ViewPort(C г ~ ) 
EXGD4,A7 
MOVE.L CA6)+,-CA7) 
JSR gViewPort 
EXGD4,A7 
RTS 

END-CODE 


CODE LookAt С left top right bottom - ) 


EXGD4,A7 


MOVE.L 12CA6),-CAT) 


MOVE.L 8CA62,-CA7T) 
MOVE.L 4(А62,-(АТ) 
MOVE.L (А6),-(АТ) 
ADDA.W #16, Аб 

JSR gLookAt 
EXGD4,A7 


RTS 
END-CODE 


CODE ViewAngle С angle - ) 


EXGD4,A7 
MOVE.L (Аб2%,-(АТ) 
JSR ду iewAngle 
EXGD4,A7 
RTS 

END-CODE 


CODE Identity 
EXGD4,A7 
JSR gIdentity 
EXGD4,A7 
RTS 

END-CODE 


CODE Scal ( xfactor yfactor zfactor - ) 


EXGD4,A7 
MOVE.L 8(А6),-(АТ) 
MOVE.L 4(А6),-(АТ7) 
MOVE.L CA6),-CA7) 
ADDA.W #12, Аб 
JSR gScale 
EXGD4,A7 
RTS 

END-CODE 


CODE Translate  ( dx dy dz ~ D 


EXGD4, A7 
MOVE.L 8CA6),-CAT) 
MOVE.L 4CA62,-CAT) 
MOVE.L CA62,-CA7) 
ADDA .W #12, A6 
JSR gTranslate 
EXGD4,A7 
RTS 

END-CODE 


CODE Pitch С xangle - ) 


EXGD4,A7 


MOVE.L CA6)+,-CAT) 
JSRgP itch 
EXGD4,A7 
RTS 

END-CODE 


CODE Yaw С yangle - ) 
EXGD4,A7 
MOVE.L €A6)+,-CA7) 
JSRgYaw 
EXGD4,A7 
RTS 

END-CODE 


CODE Rol € zangle ~ ) 
EXGD4,A7 
MOVE.L CA6)+,-CA7) 
JSRgRo11 
EXGD4, A7 
RTS 

END-CODE 


CODE Skew € zangle - ) 
EXGD4,A7 
MOVE.L €A6)+,-CA7) 
JSR gSkew 
EXGD4,A7 
RTS 

END-CODE 


CODE Transform ( src dst - ) 


EXGD4,A7 
MOVE.L 4(А62,-САТ) 
MOVE.L CA6),-CAT) 
ADDA.W #8, Аб 
JSRgTransform 
EXGD4,A7 
RTS 

END-CODE 


CODE Clip3D С srcl ѕгс2 9341 dst2 - flag 
) 


EXGD4,A7 
CLR.W -CATD 
MOVE.L 12(А6),-САТ) 
MOVE.L 8CA6),-CAT) 
MOVE.L 4CA6),-CAT) 
MOVE.L €A6),-CA7) 
ADDA .W #16, A6 
JSRgC1 ip3D 
MOVE.W (A72*,00 
EXT.L 00 
MOVE .L 00,-(А6) 
EXGD4,A7 
RTS 

END-CODE 


CODE SetPt3d С pt3D x yz - ) 


EXGD4,A7 
MOVE.L 12(А6),-САТ) 
MOVE .L 8САб), -САТ) 
MOVE.L 4CA62, -CAT) 
MOVE.L (A62,-CAT) 
ADDA .W #16, Аб 
JSRgSetPt3D 
EXGD4,A7 
RTS 

END-CODE 


CODE SetPt2d € pt2D x y - ) 


EXGD4, AT 

MOVE.L 8(A62, -САТ) 
МОМЕ Е 4(А6),-САТ) 
MOVE Е (A62,- (A7) 


ADDA .W & 12, Аб boxArray i 24 * + -> box 


JSR gSetPt2D testRect 
EXGD4,A7 box .рі1 .x 8 hi 
RTS box .pti .y @ hi 
END-CODE box .pt2 .x @ hi 
box .pt2 .y @ hi call SetRect 
\ Translation of Boxes.pas example into Forth follows testRect -1 -1 call InSetRect 
Yu YY muRect testRect testRect call SectRect 
IF drop 0 leave THEN 
x ; mach LOOP 
y 4 * ; mach i 
28%: mach 
: МакеВох ( | pix ply piz p2x p2y p2z box ii - ) 
: pti ; mach call random 70 mod 15 - 1 call FixRatio -> pix 
: .pt2 12%; mach call random 70 mod 18 - 1 call FixRetio -> ply 
0 -> plz 
15 CONSTANT BoxCount 
Variable MyPort 104 vallot call random 30 mod abs 10 + 1 call FixRatio pix + 
\ grafPort is 108 bytes long -) p2x 
Variable MgPort3D 150 vallot call rendom 45 mod ebs 10 + 1 call FixRatio ply + 
N graf3DPort is 154 bytes long -) p2y 
Variable БохАггау 24 BoxCount * vallot call random 38 mod abs 10 + 1 call FixRatio piz + 
N BoxCount * 2% point3D 6 3 long words -) p2z 
Variable nboxes \ 8 of boxes made 
Variable MyBox 20 vallot N 24 bytes for 2% point3d nyRect р1х hi ply hi p2x hi p2y hi call SetRect 
Verieble р1 8 vallot \ point3d 
Veriable p2 8 vallot N point3d chkBox IF 
Variable myRect 4 vallot \ Rect pix myBox .ptl .x ! 
Variable testRect 4 vallot N Rect ply myBox .pt1 .y ! 
piz myBox .pt1 .z ! 
: DrewBrick ( pt1 pt2 | tempRgn - ) р2х myBox .pt2 .x ! 
call NewRgn -? tempRgn p2y myBox .pt2 .y ! 
p2z myBox .pt2 .z ! 


call OpenRgn 
pti .x € pti y 8 pt! MoveTo3D 6 -> ii 
y 


26 
pti .х@р{!. ‚2 @ LineTo3D nyBox БохАггау nBoxes 6 24 * + 24 cmove 
pt2 .x € pti .y @ pt2 .z ё LineTo3D 
pt2 .x @ pti .y @ pt1 .z ё LineTo3D BEGIN 
T4. 


pt1 .x @ pti y @ pti LineTo3D myBox .ptl .y ё БохАггау ii + .pt2 .u @ » 
tempRgn call CloseRgn myBox .pt2 .y ё БохАггау ii + .р{1 .y @ > and 
tempRgn white call FillRgn myBox .pt1 .x € БохАггау ii + .pt2 .x @ < 
myBox .pt2 .x 6 boxArray ii + .ptl .x @ < and or 
call OpenRgn WHILE 
pti .x @ pti у ё pt2 .z 6 MoveTo3D 24 +) ii 
pti .x € pt2 .y @ pt2 .z 6 LineTo3D REPEAT 
pt2 .x € pt2 у € pt2 .z 6 LineTo3D ii 24 / -> ii 
pt2 .x € pti .y ё pt2 .z 6 LineTo3D 
pti .x @ pti .y @ pt2 .z 6 LineTo3D ii 1% nBoxes 6 DO 
tempRgn call CloseRgn boxArray i 1- 24 * + 
tempRgn gray call FillRgn boxArray i 24 * + 
24 cmove 
call OpenRgn -] *loop 
pt2 .x @ pti y 6 pti .z 6 MoveTo3D myBox boxArray ii 24 * + 24 cmove 
pt2 .x @ pti .y @ pt2 .z 6 LineTo3D 
pt2 .x 6 pt2 .y ё pt2 .z 6 LineTo3D 1 nBoxes *! 
pt2 .x 6 pt2 у @ pti .z 6 LineTo3D THEN 
pt2 .x € pti y @ pt1 .z ё LineTo3D j 
tempRgn call CloseRgn 
tempRgn black call FillRgn : drawGrid 
11 -10 DO 
white call penpat i 10 * 1 call FixRatio -100 1 call FixRatio 0 
pt2 .x @ pt2 .y @ pt2 .z 6 MoveTo3D MoveTo3D 
pt2 .x @ pt2 .y @ pt1 .z ё LineTo3D | i 10 * 1 call FixRetio 100 1 call FixRetio 0 
pt2 .x @ pti y 6 pti .z ё LineTo3D LineTo3D 
call pennormal LOOP 
tempRgn call DisposRgn 11-10 DO 
Р -100 1 call FixRatio i 10 * 1 call FixRatio 0 
MoveTo3D 
: hi -16 scale ; 100 1 call FixRatio i 10 * 1 call FixRatio 0 
LineTo3D 
: chkBox ( | box - ) LOOP 


1 € flag ) 
nBoxes @ 0 00 
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: restore.screen 
call drawmenubar 
call frontwindow 
grayrgn 6 call paintbehind 
call showcursor 


: main 

init3d 

call hidecursor 

myPort call OpenPort 

myPort3D Open3DPort 

myPort portRect * ViewPort 

-100 1 call FixRatio 75 1 call FixRatio 
100 1 call FixRatio -75 1 call FixRatio 

LookAt 

30 1 call FixRetio ViewAngle 

Identity 

20 1 call FixRatio Rol 

70 1 call FixRatio Pitch 


BEGIN 
myPort3D SetPor t3D 
0 nBoxes ! 
BEGIN makeBox nBoxes @ boxCount = UNTIL 


white call penPat 
black call backPat 
myPort portRect + call EraseRect 


drawGr id 


0 пВохез 6 1- 00 
boxArray i 24 * + 
dup .pti swap .pt2 DrawBrick 
-1 *LOOP 


?terminal UNTIL 
restore.screen 
bye 


д 


NEW.WINDOW Boxes 

“ Boxes” Boxes TITLE 

0 0 20 20 Boxes BOUNDS 

Plain Visible NoCloseBox NoGrowBox Boxes ITEMS 


600 5000 terminal Box 
‚ go.box activate main ; 


: start 
Boxes add 
Boxes Box build 
Box go.Box 
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‚С To create a turkey application ) cr 
‚С type TURNKEY START BOXES ) 


Listing 2: MPW Assembly glue code for accessing the Graf 3D 
Pascal library 


TITLE 'Graf3D glue code for Mach2’ 
BLANKS OFF 

PRINT OFF 

INCLUDE ‘Traps.a’ 

INCLUDE ‘ToolEqu.a’ 

INCLUDE ‘QuickEqu.a’ 

INCLUDE ‘SysEqu.a’ 

INCLUDE ‘Graf3DEqu.a’ 

PRINT ON 
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GrafGlue MAIN 
JMP  InitGrf3D 
JMP — Open3DPort 
JMP C SetPort3D 
JMP  GetPort3D 
JMP МоуеТо20 
JMP МоуеТо30 
JMP LineTo2D 
JMP  LineTo3D 


JMP Моуе20 
JMP Move3D 
JMP  Line2D 
JMP  Line3D 
JMP  ViewPort 
JMP — LookAt 


JMP  ViewAngle 
JMP Identity 


JMP Scale 

JMP C Translate 
JMP Pitch 

JMP Yaw 

JMP Roll 

JMP Skew 

JMP Transform 
JMP  Clip3D 


JMP — SetPt3D 
JMP C SetPt2D 
END 


Listing 3: МРУ assembly / link script for generating the 
9730 resource (to be put into the MACH.RSRC file) 


Asm Graf3dglue.a -1 
Link Graf3dglue.a.o д 
(Libreries)Interface.o à 
-rt gr3D-1 -o Graf3dglue -1 > Graf3dglue.map 
Listing 4: The original Boxes example (from TML Pascal) 
PROGRAM Boxes; 


( Boxes demonstrates the use of the Three Dimensional 
Quickdraw package Graf3D. 


Boxes .Pas 
*none* 


Pascal source: 
Resources: 


This program is from Apple's Lisa Software Supplement, 
modified for TML Systems Pascal compiler. 


USES MacIntf, FixMath, Gref3D; 


CONST boxCount 


- 15; 
keyOrMouse = 


10; 


TYPE Вох30 = 
RECORD 
pti: Point3D; 
pt2: Point3D; 
END; 


VAR myPort:  GrafPort; 
myPort3D: Port3D; 
boxArray: ARRAY [8..boxCount] OF Box3D; 


nBoxes: INTEGER; 
i: INTEGER; 
dummy: EventRecord; 


PROCEDURE DrawBrick(pt1, pt2: Point3D); 
( drews а 3D brick with shaded faces. 
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only shades correctly іп one direction. 


VAR tempRgn: RgnHendle; 

BEGIN 
tempRgn := NewRgn; 
OpenRgn; 
MoveTosD(pt1.X, pt1.Y, pt1.Z); ( front face, у=у1 ) 
LineTo3DCpt1.X, pt1.Y, pt2.Z); 
LineTo3D(pt2.X, pt1.Y, pt2.Z); 
LineTo3DCpt2.X, pt1.Y, pt1.25; 
LineTo3DCpt1.X, pt1.Y, pt1.2); 
CloseRgn( tempRgn); 
FillRgnCtempRgn, white); 


OpenRgn; 

МоуеТо30(р&1.Х, pt1.Y, pt2.Z); ( top face, z=z2 } 
LineTo3D(pt1.X, pt2.Y, pt2.Z); 

LineTo3D(pt2.X, pt2.Y, pt2.Z); 

LineTo3D(pt2.X, pt1.Y, pt2.Z); 

LineTo3DCpt1.X, pt1.Y, р%2.7); 

CloseRgn(tempRgn); 

FillRgnCtempRgn, gray); 


OpenRgn; 

MoveTosD(pt2.X, pt1.Y, pti.Z); ( right face, х-х2 ) 
LineTo3DCpt2.X, pt1.Y, pt2.Z); 

LineTo3D(pt2.X, pt2.Y, pt2.Z); 

LineTo3D(pt2.X, pt2.Y, pti.Z); 

LineTo3DCpt2.X, pt1.Y, pti.Z); 

CloseRgn(tempRgn); 

FillRgn(tempRgn, black); 


PenPat(white); 

MoveTo3DCpt2.X, pt2.Y, pt2.Z); ( outline right ) 
LineTo3DCpt2.X, pt2.Y, pt1.25; 

LineTo3D(pt2.X, pt1.Y, pt1.Z); 

PenNormal ; 


DisposeRgn(tempRgn); 
END; 


PROCEDURE MakeBox; 

LABEL 1; 

VAR  myBox: Box3D; 
i, j, h, v: INTEGER; 
pl, p2: Point3D; 
myRect: Rect; 
testRect: Rect; 


BEGIN 
pi.x := FixRatioCCRandom mod 70 - 15), 1); 
р1.у := FixRatioCCRandom mod 70 - 10), 1); 
pl.z := Ø; 
р2. р1.х + FixRatio((10 + ABSCRandom) MOD 30), 1); 


x ‚= 
p2.y := pl.y + FixRatio((18 + ABSCRendom) MOD 45), 1); 
p2.z := pl.z + FixRatio((18 + ABSCRendom) MOD 35), 1); 


( reject box if it intersects one already іп list ) 


SetRect(muRect, HiWord(pl.x), Н1Мог9(р1.у), HiWord(p2.x2, 


HiWord(p2.y)); 


FOR i := 0 TO nBoxes - 1 DO BEGIN 
WITH boxArrayli) DO 
SetRectCtestRect, 
HiWord(pti.x), 
HiWord(pti.y), 
HiWord(pt2.x), 
HiWord(pt2.y)); 
InSetRect(testRect, -1, -1); 
IF SectRect(myRect, testRect, testRect) THEN goto 1 
END; 
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nyBox.pt1 := pl; 
myBox .pt2 := 


boxArrey[nBoxes].pt1 : 


p2; 


( calc midpoint of box and its distance from the eye ) 
1 := Ø; 
myBox.pti; ( sentinel ) 


boxArray(nBoxes].pt2 := myBox.pt2; 


WHILE 


CCmyBox.pti.y > boxArraylil].pt2.y) AND (CmyBox.pt2.y 


boxArraylil.pti.y)) OR 


CCmyBox.pti.x < boxArrayli).pt2.x) AND (myBox.pt2.x 


boxArraylil.pt1.x)) DO 


inc(i); ( insert in order of dist ) 


› 


‹ 


FOR j := nBoxes DOWNTO i + 100 БохАггау[]] := boxArraylj - 11; 
БохАггау[1] := myBox; 


ВЕС 


I: 
END; 


іпс(пВохев 2; 
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IN ( main program } 


FlushEventsCeveryEvent, 0); 


InitGraf CéthePort); 
InitCursor; 


HideCursor; 
OpenPortCémyPort?); 
Open3DPor t CémyPor t 3D); 


( put the image in this rect ) 


ViewPort(nyPort .portRect); 


( aim the camera into 3D space } 


LookAt(FixRatio(-100, 1), 


FixRatio(75, D, 
Ғіхбаі10(100, 1), 
FixRatio(-75, 12); 


( choose lens focal length ) 


ViewAngle(FixRatio(30, 12); 


Identity; 


RollCFixRatioC20, 122; 
Pitch(FixRatioC70, 122; ( roll and pitch the plane ) 


REPEAT 


nBoxes := 0; 
REPEAT 
MakeBox 
UNTIL nBoxes=boxCount; 


PenPat(white); 
BackPat(b lack); 
EraseRect(myPort.portRect); 


FOR i := -10 TO 10 DO BEGIN 
MoveTo3DCFixRetioCi*10, 1), FixRetio(-100, 1), 0); 
LineTo3DCFixRatioCi*19, 1), FixRatioC100, 1), 0); 
END; 


FOR i := -19 TO 10 DO BEGIN 
MoveTo3D(F ixRatioC-100, 1), FixRetioCi*10, 1), Ø); 
LineTo3DCF ixRatioC100, 1), FixRatioCi*10, 1), Ø); 
END; 


FOR i :- nBoxes-1 DOWNTO 0 00 
DrawBr ickCboxArray[i].pt1,boxArrey[i].pt2); 


UNTIL OSEventAvailCkeyOrMouse, dummy); 


END. 
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Forth Forum 
Objective Activities in Forth 


Objects in Forth, International Resources & A 
Priority TaskScheduler 


One of Forth's great advantages is its extensibility. Since the 
Forth compiler is just made up from other Forth words, and the 
data structures into which each new word is compiled are very 
well documented and accessible to the user, you can very easily 
rewrite the compiler and thereby define your own language. 
(These comments are obvious to the seasoned Forth user; I've 
just repeated them to emphasize the difference to the more 
‘canonical’ languages like Pascal or C). 

With a language as flexible as Forth (very much like LISP in 
that aspect), itis no surprise that many have set out to create their 
own language on top of a Forth kernel. Famous examples are the 
object-oriented extensions ForthTalk and, of course, NEON. 
While ForthTalk (which has been covered by Paul Snively in 
MacTutor V3#2) seems to be alive and well, and still offered by 
Creative Solutions in their newsletter, NEON seems to have been 
all but abandoned by their creator, Kriya Systems. After the 2.0 
update, more than a year ago, no more NEON news. And it was 
such an elegant implementation of object-oriented program- 
ming! Judged from bulletin board posts and letters I receive every 
now and then, many of you must be more than disappointed at the 
slow disappearance of NEON from the scene of Macintosh 
languages. 

It is about a recent attempt to extend and -maybe- resurrect 
NEON, and about several other projects of object-oriented exten- 
sions to Mach2 Forth, that I wish to report this month. A lot of the 
information I am presenting comes from discussions and post- 
ings on the Mach2 roundtable on GEnie; therefore this column is, 
again, somewhat biased towards Mach2. MacForth users, please, 
read on and comment; a standard for an object oriented Forth 
would be appreciated by most of us. 


Object Orientation in Forth 


Why would one choose Forth to implement an object- 
oriented language? Besides the built-in extensibility of the Forth 
compiler, some aspects of object orientation are already con- 
tained in Forth. As a reminder, an object is a structure that 
contains not only data, but also procedures: methods, which can 
operate on the contents of the object or on other data. Example: 
an array of integer numbers which, given an index n, automati- 
cally returns the address of the nth element. The classical Forth 
definition of a *defining word' for arrays with 32 bit-size ele- 
ments is: 
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: ARRAY CREATE C 8 - ) 4 * АШОТ 
( reserves 8 cells in the dictionary ) 
DOES» Сп <adr> - adr ) SWAP 4 * + ; 


The definition of an array of 100 long integer numbers would 
then be 100 ARRAY myArray, while 47 myArray puts the address 
of the 47th element of myArray on the stack. When the array is 
first defined, the CREATE part of the definition is executed, and 
space is reserved in the dictionary for the array's contents. In 
object-oriented lingo, this would be called creation of an 
‘instance’ myArray of the ‘class’ ARRAY. myArray’s ‘instance 
variables' would correspond to the space reserved in the diction- 
ary for the 100 32-bit numbers, and its one and only ‘method’ 
would be the DOES» part of the definition, which is invoked 
when the word myArray is executed. 

If you now extend the definition ARRAY like this: 


: ARRAY CREATE 4 * ALLOT 
DOES?» swap Сп «adr? msg - adr ) 
CASE 


dr: 2 SWAP 4 * * ENDOF 
) SWAP 4 * * 6 ENDOF 


1 OF € ad 
2 OF € at: 
З OF € to: 2 SWAP 4 * + ! ENDOF 


47 addr: myArray would return the address of the 47th 
element, 47 at: myArray would return its value, and з 47 to: 
myArray Would store 3 in that cell. 

myArray сап therefore be viewed as an ‘object’ to which you 
can send ‘messages’ that determine the method used on its 
contents. myArray has three methods defined, addr:,at:, and 
to:, which have the method selectors 1, 2 and 3. 

This example showed you one aspect of object-orientation, 
encapsulation of the data structures: you access the object’s data 
by an interface given by the messages that are sent to it. No other 
access would be possible (although in this case it is easy to 
circumvent that restriction, if one does it deliberately). The other 
aspect - not covered by the example - is inheritance of methods 
and data structures: we also need super- and subclasses, auto- 
matic message passing to classes further up in the hierarchy, 
method override, and so on. 

Also, the example I gave resolves method references at run 
time (‘late binding’). This takes time, and if message and object 
are already defined at compile time, the compiler should resolve 
the reference so that the code generatedfori at: myArray does 
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not take any longer than a simple indexed fetch (like myArray i 
4 x + Q). This case is called ‘early binding’. 

Let me now describe the three projects of object-oriented 
extensions for Mach2 that I'm aware of and their basic differ- 
ences. 


Object Oriented Extensions for Mach2 


One attempt to create a NEON-like environment to Mach2 
came from Aleksey Novicov, of Palo Alto Shipping, who devel- 
oped a preliminary version of his object oriented system, called 
ОРЕХ, whose syntax is very NEON-like. Following parts of 
Aleksey's description of OPEX: 


Brief Introduction to OPEX (v0.50): 
An Object-oriented Programming Extension 
for MACH 2 
Aleksey Novicov 


...ОРЕХ contains all of the elements of an object-oriented 
programming environment. This includes the ability to define 
CLASSES, public OBJECTS of various classes, INSTANCE 
VARIABLES, and METHODS thatare called by SELECTORS. 
Also, a class can be defined as having a SUPER CLASS, and thus 
inherit all of the data structures and methods of that super class. 
All of the methodlobject binding is currently static only (i.e., only 
compile-time binding, no run-time binding yet). 

... Two new vocabularies are present called OBJECTS and 
IVARS. In normal operation no special consideration need be 
given to these vocabularies. However, if any public objects are to 
accessed, then the OBJECTS vocabulary must always be present 
in the search order. 

..Ihis a list of words that currently are available in 
OPEX...: 


: CLASS ; CLASS ;M :M 
BYTES ¿SUPER OBJECT MW! 
мие ЗЕСМЕМТ PERMANENT INITALL 
(abs) 


Also, the following MACH 2 words have been enhanced to 
work with OPEX: 

WORKSPACE NEW-SEGMENT TURNKEY 

There are many things that still need to be implemented. 
Some of the obvious include dynamic binding, support of vari- 
ablelength ARRAYSs,anddynamicobjectallocation on the heap. 
Also, the special objects, SELF and SUPER, still need to be 
implemented. 

More extensive error handling will be implemented to aid 
the programmer. Hopefully, OPEX will become more robust as 
time goes on without sacrificing speed. Whatever the case 
however, it will still run quite fast by virtue of the subroutine- 
threaded FORTH that it was built upon. 

The current version does not yet support multi-tasking. 
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However,any programs written with OPEX that use a single task 
will work fine.” —Aleksey Novicov 


Inthefollowing,someexamplesofactual OPEX code which 
shows the NEON-like syntax: 


:CLASS INT «SUPER Object 
2 BYTES 


:M PUT: MW! ‚М 
:M GET: мне ‚М 
¿CLASS 


N Class definitions must start with :CLASS, end with 

\ ;CLASS, and have a SUPER class. Methods definitions 

\ must begin with :M and end with ;M. Methods names must 

\ always end with а colon. MW! and MW@ respectively 

V store and fetch а 16-bit integer to and from the object and 
N data area that is pointed to by the topmost value on the 

N object stack. 


:CLASS Point «SUPER Object 


INT x 

INT y 

:M PUT: PUT: у PUT: x ;M 

:M GET: GET: x GET: у ;M 
¿CLASS 


\ Selector ог methods names can be reused without worry. 
\ The method of the class of a particular object will always 
\ be correctly called. 


:CLASS REGION «SUPER Object 
С for use with QuickDraw regions ) 
LongINT RgnHandle 


:М OPEN: CALL NewRgn RgnHandle ! 

CALL OpenRgn ;М 
:M CLOSE: RgnHandle 6 CALL CloseRgn ;M 
:M DRAW: RgnHendle 6 CALL FremeRgn ;М 
:M PAINT:  RgnHendle @ CALL PaintRgn ;M 
:M ERASE: — RgnHandle 6 CALL EreseRgn ;М 
:M INVERT: RgnHandle 6 CALL InvertRgn ;М 
:M WITHIN: ( “location - flag ) 


@ RgnHandle @ CALL PtInRgn ;М 


:М MOVE: { dh dv - ) 
RgnHendle 6 dh dv CALL OfSetRgn ;М 
;CLASS 


V In all of the above methods “GET: RgnHandle^ could ve 
\ been used instead of "RgnHandle 6” and 

N “PUT: RgnHandle^ could've been used instead of 

V “RgnHandle !^. The advantage to accessing instance 

V variables in this manner is speed. Also note that any 
N method can have its own set of local variables (see 

\ MOVE: method). 


POINT thisPt 
POINT thatPt 
INT x INT у 
3 put: x 4 put: y 


get: x get: у put: thisPt С set thisPt to some value ) 
get: thisPt swap put: thatPt С swap x and у for thatPt ) 


OPEX seems like one good step forward on the way to a 
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NEON-like environment in Mach2, even though some things 
still need to be implemented. The discussion on OPEX has been 
pretty inactive for the last few months; I encourage all of you to 
contact the author or Palo Alto Shipping on the GEnie 
RoundTable to make this project advance. 

The second OOPS-Forth that can be found on GEnie has 
been written by Jim Straus. His package is much less NEON-like. 
In his own words: 


OOPS-Forth 
Jim Straus 

“Itis based on an article by Dick Pountain (of Byte fame) that 
appeared in the Journal of Forth Applications and Research 
(volume 3, number 3). The source code given in the article was 
modified to work with Mach2. This project was started because 
I've had along standing interest in object oriented programming 
and I wanted an object oriented language where I could see what 
was going on inside. I started from the article by Dick Pountain 
so that I could see how someone else had done it. I figured that 
it would be easier to start with a basic outline for the extensions. 
While implementing this package, I have come across many 
things that I would do differently. Some of these include 
removing distinction between classes and instances, allow for 
"early binding", and making the code for looking up method 
selectors much more efficient. I hope to get around to doing a 
second version, but I thought that people might want to try out an 
object oriented language in the mean time. 

Included in this package are the files: ‘Object Oriented 
Forth-Mach', which contains the defining words to create new 
classes and the definition of the root class % OBJECT. ‘Graphic 
Objects' contains some demonstration classes and instances of 
those classes. The graphical objects are points, pens (which 
understand some Quick Draw messages, such as PenPat and 
many Logo turtle-like messages, such as right: and go:). 


Inanobjectoriented language you send messages to objects. 
The general syntax in this implementation is: «argu- 
ments» object  methodselector 

[different from the NEON syntax, which would be «argu- 
ments» selector: object —JL] 

where the «arguments» depend on the method selected and 
"^v is the word that sends the message to “object” telling it to look 
for the method associated with *methodselector" and to execute 
the code for that method. In this implementation both classes and 
instances of classes are objects and may be sent messages. 
Classes define both the methods to which the class will responds 
and also the methods to which instances of that class will 
respond. [This is also differentfrom NEON, where classes aren't 
objects. —JL] | 

New classes inherit methods from their superclass. For 
example, the class %polygon defines its own methods, but 
polygons also recognize the methods of their superclass Фреп. 
Also note that the class %polygon can override the methods іп 
%pen to either replace or enhance them. The top of this hierarchy 
of classes is always the class ФОВЛЕСТ. ФОВ/ЕСТ is special 
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in that it handles creating new instances of a class, handles 
unrecognized method selectors and provides a general frame- 
Work for what methods every object understands. 

Ап instance of a class contains a pointer to its class and 
contains the actual storage needed by the instance. This allows 
each instance to have different values in its variables. For 
example, the two polygons “fred” and “sam” each understand all 
of the same methods, but when each is asked to “N draw" itself, 
they display as different shapes and at different locations. This 
is because their values are different. 


. An object leaves its address on the stack. The word '^" 
(redefined from the Mach2 line commentor) calculates a hash 
value for the word following it (the method selector) and sends 
that value to the object. The object looks up the method selector 
with a case statement and executes its code. Any values needed 
by the method should be left on the stack beforehand. For 
example, “fred\draw” would cause fred to draw itself and “10 bic 
Ngo:" would cause bic to move 10 steps in whatever direction it 
was headed." —Jim Strauss 


Here is an empty class definition: 


CLASS:- classname 
SUPERCLASS:- %ОВУЕСТ 


ENDCLASSVARS; 


CLASS METHODS :- 
ENDMETHODS ; 


ENDINSTVARS; 
INSTANCE METHODS: - 


ENDMETHODS; 
ENDCLASS; 


A code fragment written in this dialect would look like: 


CLASS:- %polygon 
SUPERCLASS:- Zpen 


ENDCLASSVARS ; 


CLASS METHODS :- 
ENDMETHODS; 


INT INSTVAR SIDES С number of sides in polygon ) 
INT INSTVAR LENGTH 
( the length of the sides of the polygon ) 


ENDINSTVARS; 

INSTANCE METHODS: - 
~ init :: super\ init 20 LENGTH ! 4 SIDES ! ;; 
~ print :: SIDES € . LENGTH 6. 


super print 
." X length: \ sides: “ ;; 
“а :: self N class OVER N related? 
IF DUP super\ = 
OVER \ sides SIDES @ = AND 
SWAP X length LENGTH @ = AND 
ELSE DROP 0 THEN ;; 
:: 168 С 368d) SIDES ё / С find angle ) 
SIDES 6 0 DO 
LENGTH @ super\ go: DROP 


" draw 
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DUP self \ right: DROP 
LOOP DROP self ;; 


" go: self \ length: \ drew ;; 
" Sides: :: SIDES ! self ;; 
" Sides :: SIDES e ;; 
" length: :: LENGTH ! self ;; 
" length :: LENGTH ё ;; 
" times: :: 168 С 368d) OVER / 
SWAP 0 DO 
self X draw DROP 
DUP self N right: DROP 
LOOP DROP self ;; 
ENDMETHODS; 
ENDCLASS; 
DECIMAL 


call frontwindow call setport 
100 100 Zpen N setcenter DROP 
С initialize the class Spen ) 
0 integer bic ( create а variable for а new object ) 
“реп \ new bic to С an instance of class Фреп ) 
0 integer fred Са variable Гог а new box ) 
Zpolygon X new fred to 
С an instance of class %polygon ) 
0 integer sam 
Zpolygon \ new sam to С create another polygon ) 
9 integer poly 
Zpolygon X new poly toC create another polygon ) 


This example - although incomplete - may give you an 
impression how OOPS Forth code looks like in Jim Straus' 
system. I'll leave it with that; for a complete description and the 
source code you should check on the Mach2 roundtable on 
GEnie. 

The third Mach2-OOPS, written by Wayne Joerding from 
Pullman, WA, is similar to the one just described in that it uses 
class defining objects (CDOs) to create instances or subclasses of 
aclass. Wayne has prepared, and almost finished, a big article on 
his implementation which we'll hopefully print in one of the next 
issues. Theimplementation allows early and late binding. Again, 
a code fragment probably serves best to explain the syntax: 


\ 222222 Variable size Array Class ========= 
Integer Def ine.Child.Class 
: Instance 
I.Ver Max. Index 
\ max size of array, for error checking 
І.Уаг Length 


N number of current elements in array, 
\ measured by cells 
I.Pntr Start 
\ points to the start of array memory 
Hide 
:M Describe 
сг 
.” — Instance Information 2 
Мате 
cr .^ Max Length in cells 
Mex.Index 6 1%. 
cr .? Cell size in bytes =” Int ё. 
Pr.Imeths 


"М Store C6 x i - 2 
\ Store value x in array for index = i, 
\ first cell has index of zero 
Max.Index 6 over < over 0 < or IF 
.” index out of bounds” abort THEN 
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\ ‹— error checking 

Int ë * Start + ! ; 

"М Retrieve C i — ) 

\ Retrieve value of array for index = i. 

Мах. Index 6 over < over Ø < or IF 
.” index out of bounds” abort THEN 
V <- error checking 

Int @ * Start + @ : 

; Instance 


‘Class 
:M Маке. Instance Спс - ) С <name>» -IN- ) 
\ Array instance of size n cells, cell size of c 
CREATE immediate 
ins .Кеу 6 
, \ Store key to methods of parent class 
\ save cell size in ‘Int’ variable 
\ make and save Max. Index 
\ of array for error checking 
0, N init current Length to zero 
* ins.Size 6 * allot 


DOES»? dup 8 Selector С ins.PFA - ins.PFA key ) 


;Class 


Integer Name.Child.Class Array (nc-) 


You notice the strategy: The class INTEGER is just another 
object to which we can send the message Define.Child.Class, 
followed by a subclass definition; right after that definition, we 
send the message Name.Child.Class, followed by the subclass 
name. А bit unusual for those used to the NEON syntax, but it 
works very well. Typical code would look like: 


V - Array test — 

100 Array Meke.Instance myArray 
3 47 myArray Store 

47 myArray Retrieve . cr 


V 7 test of String — 

20 String Make.Instance StrHello 
: hel .^ This is StrHello" ; 
“hel 4 + StrHello Store 

: chk.StrOb StrHello Print ; 


Ihope you are anxious to see the actual article, which should 
follow soon. 


NEON - still breathing (2!) 


NEON’s problem has been - I think - to have been on the 
market too early; there were just too may bugs left in the first 
releases. NEON 2.0 always behaved quite nicely in my hands; 
others said it still crashed very often. Anyway, looking back one 
could perhaps consider NEON 2:0 the first mature release, and it 
is a shame that there has been only silence from Kriya Systems 
for so long. 


Extending Neon 
Jim Savidge 
Recently, an avid NEON user, Jim Savidge, has taken the 
NEON kernel and built its own extensions on top of it, making it 
into an even more powerful system than NEON itself. I will give 
you a quick description of his enhancements. 
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(Ехсегрі Нот СЕше) 

Category 2, Topic 14 

Message 47 Sat Jan 02, 1988 

J.T. SAVIDGE at 23:41 CST 

For those who are interested | have made some very inter- 
esting and powerful extensions to Neon that might have some use 
in a Mach 2 implementation. | am at the moment trying to patch 
Neon to work ona Mac |1. Nowthat Neonis no longer onthe public 
market and that it uses self-modifying code etc.., wish me luck. | 
rather have my extensions in use in an expanding market. (hint 
hint Mach users) Here is a simple list of my extensions: 


1) Multiple-inheritance w/ no limit to number of super classes, 
User can pick which class a message will be sent to, and which 
particular class variable it is sent to, (of the classes many 
superclasses.) 

2) Private methods. The message name will no longer be 
recognized after the class definition is close off. 

3) Local Procedures. At the Forth level. This allows a local 
Forth word, (a Forth definition inside a Forth definition) to access 
the local variables. 

4) A multi-window, single-stepping debugger, with multiple 
levels of break-pointing. (i.e. breakpoint to test a word, pop into 
debugger while testing, breakpoint test, continue last break, then 
even go back to where you were on the first breakpoint, etc..) 
Windows include: trace window, Tib window with In indicator, 
Stack window that shows decompiled meanings of Parameter, 
Return, and Methods stacks. 

5) Unique-methods. Creating a single object with methods of 
its own. 

6) Clone-Object and Copy-Object words. 

7) Echo-to-disk 

8) Saving off of Method and Ivar names for later Decompiling/ 
Debugging. 

9) Other “minor improvements”. 


If anybody would like me to contribute to an object-extension 
to Mach 2 or in creating any new Forth/Object language 
*PLEASE* contact те. 

James T. Savidge, Saturday, January 2, 1988. 


Even for those not directly interesting in object-oriented 
programming, the definitions for local procedures and the multi- 
window debugger should be very worthwhile enhancements. For 
the object-oriented part, the multiple inheritance - allowing anew 
subclass to have several superclasses - is, of course, especially 
interesting. 

A message to an object that has several superclasses, and 
which cannot be handles by the object itself, is first passed to the 
superclass which is defined first, if the superclass cannot handle 
16 it is passed further upward in the hierarchy, until the class 
OBJECT. If the method still can’t be found, the message is passed 
to the superclass which was defined second, and so on. An 
example of a class definition in Jim Savidge’s enhanced NEON 
would look like: 
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‘Class Qqq «Super Rrr 
«Super 558 
Var Qaqqvar 


:M Ааа: .^ Qqq Message " ;М 


;Class 
Qqq my0bj 


The message Aaa: can be handled directly by objects of 
class Qqq, while other messages are first passed to class Rrr, 
then to Sss. One more specialty is class picking; if you send 
Sss.Xxx: myObj, the message Xxx: will be passed directly to the 
superclass Sss. 

Private methods which are only accessible from within the 
class definition can be defined through the following construct: 


:CLASS FIRST «SUPER OBJECT 


:PRIVATE 
‚М ААА: .” AAA * ‚М 
‚М BBB: .^ ВВВ “ ‚М 
;PRIVATE 


:M ССС: .” CCC " ааа: self ;M 
:М DDD: .^ 000 ” bbb: self ;M 


¿CLASS 


FIRST ONE 


In this case, sending ccc: one would print “ССС ААА”, 
while ааа: one would result іп an error message. А new level of 
Information hiding which can be very useful. 

Ihave tested all of the above, and more, on my МасП, and 
to my great surprise (I hadn't tested NEON on the MacII yet) 
discovered that NEON 2.0 still runs on a MacII, even under 
Multifinder! It shouldn't run, though, since my cache was turned 
on, and trap calls in NEON use self-modifying code (you know, 
the old trick where you drop the trap code justin front of your feet 
and step on it)...so double surprise. Triple surprise, when Jim 
told me on the network that HIS MacII wouldn't run NEON 2.0. 
Subtle differences in system configuration probably make a big 
difference here. 

The 68020 instruction cache will allow to use self-modify- 
ing code, if an address has been executed beforehand that is equal 
to (modified address modulo cache length), since then the in- 
struction that was modified will always be fetched from memory. 
If one can make sure that the self-modifying code has stepped 
through at least 64 32-bit instructions in linear sequence before 
encountering the modified address, this might work. I have traced 
the NEON code for signs of such a behavior, but no luck. 
Somehow it works on my МасП and crashes оп Jim's...strange 
and mysterious things going on here. 

I bet you'll all like to see a full article on the NEON 
extensions. As Jim told me, that, or a commercial package, is 
under consideration, a lot depends on the availability of a more 
recent NEON release, or even the complete NEON source. The 
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future of NEON should definitely not end at this point, and any 
support from outside can only help the issue. 


Feedback Dept. Europe 


International Conversion 
Peter Freund 
Sweden 
Here’s a letter from a reader in Sweden (again those interna- 
tional keyboards and characters. ..): 


“Гат one of those non-programming, yet admiring users, 
that enjoy MacTutor ‘cause there is something worth reading 
there. 

I work for Software Plus, distributor in Sweden for several 
Macintosh and MS-DOS products. We represent products like 
TOPS, WriteNow, QuarkXPress, SuperPaint, Timbuktu, 
MacLink and companies like General Computer, SuperMac, 
Symantec (Living Videotext, Think Technologies), Farallon. I 
am the one that answers and handles communication products, 
but also companies “knowledge-base”. Ialso do some translation 
of programs and manuals. 

I know that if an article (like mine) would be published in 
MacTutor, it would help spreading Macintosh on the interna- 
tional basis and also help our company (I would have less 
annoying work.) /Well, there you go! Take your vacation now— 
JL] 

Take any text from the following letter, in any form, or 
please write any kind of program that shows how to use the 
"International Utility Package" (itoughtto be quite easy) - so my 
and all non-english-spoken peoples' job will be easier. 

Ialsokeep up a BBS (called Fenix) ona free basis when I am 
not working (using RedRyder Host). The number is +46 8 
308356. (Either I or Fenix answers the phone.) My address is: 

Software Plus 

Att: Peter Freund 

Box 2286 

600 02 Norrkóping 

+46 11 181270 

(leave a msg if I am not available) 

+46 8 308356 

(my usual number ((I work at home with translation of 
MORE right now))) 

I also send some fun [a HyperCard stack for канш І 
have created myself. Enjoy! 


This is an article I have been wanting to write for along time: 
Today 1988-10-05 (US format: 5/10/88...) 


How to handle international characters 
In the old days, before 8-bit-ASCII, different countries did 
their own modification to computers, so the national characters 


would work. In Sweden there even became two versions of 7-bit 
ASCII, “Swedish usual version" and “Swedish name version". 
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For example the old Apple II was sold in Sweden with the 

following character set: 
1”Ң5%67 () *+,-./ 0.9 : ; <=>? @ ALY 
2 АОА^ _ `ta.y z à ó à - é 

The ROM was specially modified for Sweden. The key- 
board was also modified, in a similar way as a the swedish 
keyboard nowadays on a Macintosh. 

Then came the Macintosh, with RAM-based fonts and 
complete 8-bit ASCII. Most of the european (all(?) west-euro- 
pean) characters can now be handled in a general way. This 
means that all well-written programs can be used internationally 
without modification. 

Well, the problems are small compared to our friends in 
Norway and the IBM PC. When IBM designed their own version 
of 8-bit-ASCII, they “forgot” the norwegian/danish character 0. 
(An error even Apple did with their early version of Courier in 
Apple LaserWriter...). This means that all ROMs in Norway/ 
Denmark has to be specially made for any MS-DOS machine, 
and the two characters $ and Y is replaced by ø and Ø. 

There exist more versions of 8-bit-ASCII (Digital Decmulti, 
Hewlett Packard Roman 8). PostScript use special names for 
characters. Now let us first look at Macintosh and IBM PC! 

When translating between a Macintosh and a IBM PC, it is 
difficult to only use TOPS or Dynafile for text files. There has to 
be an international(!) version of MacLink for handling the 
international characters correctly. With Apple File Exchange for 
conversion between Apple II and Macintosh I probably obtain 
the usual [N instead of AAO. 


For a very long time there was no program that correctly 
could use all 256 characters when communicating. Usually the 
program skipped everything above ASCII 127. Most program 
have an option nowadays (like Red Ryder 10.3) to turn masking 
of high bits off. 

Thereis two programson the Macintosh that handle commu- 
nication with swedish characters correctly: Mac Terminal (swed- 
ish version) and inTalk. The user can easily select if swedish 
(swedish 7-bit-ASCIT) is to be used or not. In MacTerminal it is 
also possible to select if incoming characters, outgoing charac- 
ters or both should be converted, and even both swedish stan- 
dards are available. 


How to communicate In Swedish? 


I guess they use some kind of conversion table. If a Macin- 
tosh is to be used as a terminal to a mini in Sweden, there are two 
conversion tables necessary. Here is the scheme: First I press the 
swedish character À on my Macintosh. The Mac communication 
program checks if this character is anything that is used for 
terminal emulation. If not, we convert this character, using 
conversion table one, into a [. Then we send the character over. 

When on the other hand the mini sends a character, we first 
check if it has anything to do with terminal emulation. Thereafter 
we convert the characters that is supposed to be sent to screen, 
using conversion table two. 

When MacTerminal, or InTalk implemented the swedish 
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character set, they did not let the user change the conversion 
tables. This means that if I want to communicate with a IBM PC 
and send text files over, I must use some special program again! 

Does it really have to be that difficult? In MS-DOS-world 
there are several programs (Enable, ProComm, plus others), 
where itis easy to modify a conversion table, with all characters, 
any way I like. There even exists a TSR (Terminate and Stay 
Resident)-program (like an INIT) that patches the serial routines 
for Swedish, so the conversion almost always works. 

Itought notto be too difficult to write a cdev that would alter 
the serial routines, in a similar way and that could be configur- 
able/turned on/off through the Control Panel. 

[Such aroutine might actually be very useful in a number of 
circumstances. I can remember the case of Versaterm Pro v.2.0 
not recognizing the new ISO Keyboard correctly (the one with the 
small return key). In that case, you wouldn't be able to use the 
arrow keys anymore to walk across a VT100 screen. This 
problem has been solved in never versions of Versaterm, but for 
the meantime it would have been extremely useful to have a 
routine available that passes serial inloutput through a conver- 
sion table like you suggested. If I can figure out how to do such 
a filter in a way that would satisfy the User Interface Thought 
Police, I might write a column on it]. 


To all hackers: 


Yet what really would improve things would be if the 
manufacturers would think a little more internationally. (In 
Inside Mac there is an "International Utility Package" worth 
looking at!) 

Now, let us look at some popular programs today (I guess 
most of you know them): 


Very Good: 

4th Dimension - sorts well, configurable, works even with 
chinese! 

MacTerminal (swedish version). 

QUED - sorts and works correctly. 

MORE - sorts correctly, handles all characters/ date func- 
tions with class. But even the sun has its spots, I cannot use the 
name “Orjan” as registration name, because it starts with Ó. 


Good(?): 

WriteNow - can handle foreign characters, but the spelling- 
checker cannot suggest any foreign characters, and also cannot 
see the difference between upper case and lower case with 
international characters. 

DiskTop - has a funny bug. Difficult to find by date, because 
DiskTop suggests international date format, but can only accept 
US-dates for input. (DiskTop 3.0.2) 


Bad (most “famous” programs work pretty well nowadays): 

FileMaker Plus - cannot sort correctly. For a DB-program, 
this is bad. (I think MS File, Reflex and Helix had/has(?) the same 
problem.) 
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Old MacPascal - not possible to write international charac- 
ters at all (above 80 hex). 
SuperPaint - cannot print on whole “A4 Letter size" (8 1/4" 
x 11 2/3"). 
. RedRyderHost - uses a font that does not even contain 


A lot of programs use Command/] and Command/[ and other 
special characters for fast menu selection, that doesn't work on 
international Systems. 

Finally asuggestion to those “desktop publishing program"- 
makers that always seems to hunt for good, new features: 
"Overlay characters"! 

Kering is a modern thing nowadays. With kerning it is 
possible to combine two characters into one. In many languages 
it is very usual (as usual as an "e" in english) to combine normal 
letters (acenorsz) with characters like ^'—^ ^*. [T recently found 
ош to my surprise, when trying to type the address on a letter to 
Czechoslovakia, that Apple left out a c with an inverted circum- 
flex, as shown below created in MacDraw, from their fonts. In 
fact, that diacritical mark does not seem to exist]. 


v 
c 


Fig. 1 Missing International Symbol 


The problem with kerning in desktop publishing programs 
today is that a value has to be specified. Yet I in most (all?) cases 
want the top character to be centered above the lower one. I can, 
with some DTP-programs, put two characters in the same place 
with kerning, but when size or font changes, the position of the 
top character goes wrong.." 

—Peter Freund 


[Thank you, Peter, for these very interesting remarks on 
international compatibility issues, a specter that has haunted the 
Macintosh scene ever since this machine was introduced. The 
fact that changing keyboard layouts ‘on the fly’ became possible 
only with System 4.1 has always been embarrassing. 

Note to our readers: Peter’s letter was accompanied by a 
file which contained the keyboard layoutresources(KCHR) for 
over ten different countries. This file is included on this 
month’s source code disk for anybody who needs it. -JL] 


A Priority Based Task Scheduler 
Clive Maynard, 
Western Australia 


This contribution was sent to us from an Australian Macin- 
tosh user and Mach2 programmer. It implements a priority-based 
scheduling system for Масһ2 tasks. 


"Dear Jorg, 
I have read your column in MacTutor for quite a time with 
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considerable interest and have found it very useful. 

I have enclosed on disk something which may be of interest 
to you for an article in MacTutor. 

The software provides a demonstration priority based sched- 
uler for Mach2. 

The basic round robin is not removed for the Mach2 task and 
Editor together with a background scheduling task. Additional 
tasks are added in such a way that they put themselves to sleep on 
completion through the execution of a word SwitchTask and 
return control to the scheduler. The scheduler determines from 
the priorities of available tasks which should be woken next, puts 
itself to sleep and wakes up the correct task. 

The result is that the minimum number of tasks are in the 
round robin when the normal Mach2 pause occurs. 

Variations which could improve speed include coding the 
scheduling task in assembler but this was developed for student 
study of operating system functions not high performance. 

Priorities may be changed through a Priority Terminal task 
window in the range O to 100. 0 corresponds to task suspension 
until the priority is raised back to a positive value. The initial 
default priority is 10 for each task. 

[As you can see from the code, the scheduler creates a task 
table for a maximum of ten tasks. For each task, its current level, 
the priority value and its address are maintained in this table. 
The level is initialized to zero. In its main loop, the task scheduler 
decrements the level of each task by its priority value. Each time 
the decrement passes through zero, the task is woken up for one 
round of execution and the level reset to 100. —JL] 

The three additional tasks run in the demonstration provide 
a simple quickdraw output. The tasks can have their priorities 
varied and easily show the effects of the priority allocation. 

The only other features which may be of interest are: 

1. The creation of anew word LVALLOT which allows 
for the creation of local arrays in words with local parameter and 
variable facilities. 

2. #IN which is an intrinsic word in UR/FORTH for the 
IBM/PC is created here using LVALLOT and the SwitchTask 
function to prevent the suspension of the other tasks when new 
priority values are being entered. 

Clive Maynard, 

Wave=onic Associates 

_ 199 Watts Road, 

Wilson 6107 

Western Australia” 


[One further remark is that one should minimize the use of 
PAUSE in this task-switching environment, and use SwitchTask 
instead to make the scheduling more effective. For this purpose, 
the word PTExpect redefines EXPECT to contain a SwitchTask. 
There are PAUSEs left (in ? TERMINAL and KEY), but this can't 
be avoided. 

The illustration shows the nice graphical output of Clive' s 
demo. —JL] 
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| Shrink Mach 2 eindos to top left corner 
Execute task words: atask, btask and ctask after loading the file 
Change priority the priority task sindow 


оқ «Oo» 
Gtask оқ «0» 
btask оқ <0» 


PRIORITIES 
Enter the task nusber followed bu 
14$ desired prioritu 
Priorities can be from О to 100 


a as >> 
Ap Dictionary — @ Kermit X364 Фамьсога 
The m HË Standard Otossar ПМ VaxKer ФАМасога Г «мса 


Fig. 2 Mach2 task scheduler output 
(on JL's usual crowded Multifinder desktop) 


The Mach2 task scheduler 


‚С Priority based multitasking on the Macintosh ) cr 
€ Original concept: D.Bryant, G.Caunt, G.Else 1987 ) 
€ Modifications end Generalisation: ) 

С C.A.Maynard 1988 Wave=onic Associates) 

( Version 1.1 060488 ) 
Decimal 
С--------------) 
( Task and window configurations Гог the necessary tasks ) 
2---------) 


400 1000 background schedulertask 
400 1000 terminal prioritytask 


new.window PriorityWindow 

* PRIORITIES? PriorityWindow Title ( create priority window ) 
40 250 110 500 PriorityWindow Bounds 

Document Visible NoCloseBox GrowBox PriorityWindow Items 
PriorityWindow Add 
О) 
С DEMO Tasks апа windows ) 
С--------------) 
400 1000 terminal task! 

400 1000 terminal task2 

400 1000 terminal task3 


new.window Task Window 

* TASK 1^ TaskiWindow Title ( create the TASK 1 window ) 
140 20 310 180 TaskiWindow Bounds 

Document Visible NoCloseBox NoGrowBox TaskiWindow Items 
Task Window Add 


new.window Task2Window 

* TASK 2” Task2Window Title ( create the TASK 2 window ) 
140 189 310 340 Task2Window Bounds 

Document Visible NoCloseBox NoGrowBox Task2Window Items 
Task2Window Add 


new.window Task3Window 

“ TASK 3” Tesk3Window Title C create the TASK З window ) 
140 340 310 500 Task3Window Bounds 

Document Visible NoCloseBox NoGrowBox Task3Window Items 
Task3Window Add 
с-————————————› 
( USER Variable definitions ) 

( ----------------) 
12 user TaskWindow 

220 user rleft 

224 user rright 


© The Definitive MacTutor, Vol. 4 


228 user гор 
232 user rbot 
236 user diff 

С create rectangle coords as user variables for each task 
) 
240 user angle 
244 user rectangle ( space for 8 bytes needed. Next slot 252) 
( ——ə——T"PnT"> — ) 
( Scheduling Task Definitions ) 
2---------------)) 
VARIABLE LevelAddr 

С Global temporary storage for the scheduler ) 
VARIABLE NTASKS С Number of runnable tasks МАХ 10) 
Q NTASKS ! ( Initialise to zero ) 
VARIABLE PTASKS 120 VALLOT 
( Storage for Level, Priority and Task Address ) 

: Wakeup Са! - ) 
( Wakeup gets the next task running given the status address ) 
Sleep status W! 
wake swap W! pause ; 


: SwitchTask 

С Call the scheduler to see who's next ) 
Sleep status W! 

wake status task-? schedulertask W! 
pause ; 


: SCHED 
с Define а general task scheduling process ) 
activate. 
begin 
NTasks 6 dup Ø@ if С only execute defined tasks ) 
9 DO 
I 12 * PTasks + dup LevelAddr ! 6 
С Get the address апа current level ) 
LevelAddr @ 4 + e С Get priority setting ) 
+ dup LevelAddr @ ! C Save new level ) 
100 - dup Ø> if 
level if necessery ) 
LevelAddr @ ! 
LevelAddr ё 8 + 6 Wakeup 
else 
drop 
then 
LOOP 
else drop then pause 
again ; 
( 


( Modify 


) 

сг 

‚С Clive Maynard’s Forth Environment extract ) cr 
‚С C. A. Maynard 020488 ) cr 


also assembler 


code LVALLOT Сп - addr 2 
( Set up а local buffer. ) 
С Only callable from а word with local variables ) 
C UNLK will clean up the stack. ) 
( USER beware of buffer overflow!!! ) 
MOVE.L CA62*,D0 С GET SIZE IN BYTES ) 
MOVEA.L — CA72*,A0 C GET RETURN INFO ) 
SUBA.L 00,А7 С NEW SP ) 
MOVE.L A7,-CA6) 
( COPY ADDRESS TO PARAMETER STACK ) 
JMP (А0) 
end-code 


. -1 CONSTANT TRUE 
0 CONSTANT FALSE 


: terminator? С char - f ) 


С check for the terminator of a number: space ог CR ) 
case 
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13 of true swap endof 
32 of true swep endof 
false swap 

endcese ; 


: PTexpect ( buffad nchars | buffadd countup - ) 
( Fills а buffer but includes Priority Task switching ) 
buffad 1 + -> buffadd Ø -> countup 
nchars 0 do 
begin 
SwitchTask 
?terminal until 
key dup emit dup buffadd C! 1 +> buffadd 1 +> countup 
"Üterminator? if leave then 
100p 
countup buffad c! ; 


: SIN ( | buffaddr - number ) 

С PC/FORTH intrinsic function!! ) 

С Collect into а 10 byte buffer and return а number input ) 
10 lvallot С set up а local buffer very carefully ) 

-> buffaddr 

buffaddr 19 PTexpect 

buffaddr number? drop ; 


-------------)) 
СА new task building word for Priority Tasks ) 
( 


Ум) 
: PBUILD ( TaskAddr | LevelAdr - ) 
( Initialise conditions for new tasks ) 
NTesks 10 = abort” Task Priority Table Full. New entry denied" 
NTasks @ 12 * PTasks + С Get offset into table ) 
dup -> LevelAdr 0 swap | СГ Set Level to zero ) 
10 LevelAdr 4 * ! ( Set Priority to de- 
fault of 102 
TaskAddr BUILD 
task build ) 
TaskAddr @ LevelAdr 8 + ! 
NTasks 6 1% NTasks ! 


7 


( Now do an ordinary 


( Save Status address ) 
С Increase task count ) 


(С м) 
С The Priority Task Definition ) 
(--------------) 


: getbuff ( | teskno priority - ) 
( priority reallocation routine) 
“іп dup .^ Task “ . -> taskno cr 
taskno МТазкз 6 < taskno 0» and if 
“Зіл dup Ø< if drop Ø then dup .^ Priority ” 
€ New priority determined 2 
priority 101 < IF 
priority dup 0= if 
cr .^ Zero or negative priority halts the task” cr 
then 
taskno 12 * 4 * PTesks * ! € Get to storage location ) 
ELSE cr .^ Priority out of renge. No change^ cr THEN 
else cr .^ Task number out of range. № change” cr then ; 


. 7) priority 


: setpriority С priority allocation task) 
activate 
begin 
taskwindow 6 call SetPort 
." Enter the task number followed by^ cr 
cr 
." Priorities can be from Ø to 100" cr 
?terminal if 
getbuff cr then 


." its desired priority” 


SwitchTask 
egain ; 
( ) 
С The other tasks ) 
( ------------------- Y > 
: DISKS 
activate 


( Initialise variables ) 
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-7 diff ! Ø angle ! 
10 rleft W! 20 гіор W! 


150 rright W! 160 rbot W! 
€ Loop through graphic changes in superb animation ) 


begin 


rectangle rleft W@ rtop W@ rright W@ rbot М6 call SetRect 


begin 
359 angle 8 - 0 
while 


taskwindow 6 call SetPort 
angle 6 10 + angle ! 
rectangle angle 6 10 call InvertArc 


SwitchTask 
repeat 


taskwindow € call SetPort 
rright W@ diff @ + rright W! 
rbot W@ diff @ + rbot W! 
rright We rleft ме - 5 < if 


T diff ! then 


rright We rleft We - 140 » if 
rectangle 0 360 call EraseRect -7 diff ! then 


0 angle ! 
SwitchTask 
again ; 
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( Get back to the scheduler ) 


( -------------------- 
С Initiate the necessary tasking operations ) 
С----------------) 


schedulertask build (С slot scheduler into round robin loop 2 
schedulertask sched 

prioritywindow prioritytask Pbuild 

prioritytask setpriority 
(--------------) 
‚С Define task insertion words to show adding tasks to priority 
system ) cr 

.C Shrink Mach 2 window to top left corner ) cr 

‚С Execute task words: atask, btask and ctask after loading the 
file ) cr 

‚С Change priority through the priority task window ) cr 
Ё(——_) 


: Atask taskiwindow task! Pbuild 
task! disks ; 


: Btask task2window task2 Pbuild 
task2 disks ; 


: Ctask task3window task3 Pbuild d 
task3 disks ; Py 
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Forth Forum 
Object Forth Project 


Object-Oriented Extension to MACH2™ Forth 
by Wayne Joerding 


[This is the first of - hopefully - several upcoming articles 
dealing with Object Forth extensions. I introduced you to some 
of the features of Wayne' s implementation in my last column. 
Now, here comes the real stuff. I checked out Wayne's code 
several times andit seems to work very well. For those of you who 
play with the source code disk before reading the article I should 
point out that you have to turn vocabulary hashing OFF before 
you try out the code; this is also explained in the article. 

Wayne Joerding is an associate professor of economics at 
Washington State University in Pullman, WA. He uses the Mac 
- with Mach2 and his object extensions - in his research on stock 
market efficiency issues. He can be reached on GEnie - 
W.JOERDING. 

Wayne went through great lengths in the implementation to 
make sure that the code works with WORKSPACE, NEW-SEG- 
MENT, and TURNKEY. Because of the way dictionary links are 
changed by his code during class compilation, this is not at all 
trivial. Read his notes carefully under this aspect. - JL] 


Introduction 


How could any programmer resist “object-oriented pro- 
gramming,” with its promise to reduce program development 
time through reusable code and improve revisability by the use 
of self-contained modules that encapsulate data structures and 
their procedures that operate on the structure. Then to find out 
that the whole thing works by passing messages to something 
called an object, it was too much to resist. But, I didn’t want to 
give up my experience with Forth, its fast code, extensible 
compiler and interactive programming style. Fortunately, it is 
possible and desirable to build an object-oriented extension of 
the Forth language, NEON is perhaps the best known example. 

Brad Cox’s excellent book Object-oriented Programming: 
An Evolutionary Approach, promotes the advantages of using a 
hybrid language derived by extending a traditional language to 
accommodate the object-oriented approach. Object-oriented 
Forth by Dick Pountain actually shows how to add abstract data 
types (objects) to Forth. Armed with these two books, I have 
developed an object-oriented extension to MACH? Forth. This 
article describes the results. My approach is not the only one, 
NEON has already been mentioned and there are postings on 
GEnie from others who are making object-oriented extensions to 
FORTH. However, each approach has unique features and 
limitations, thus an additional objective for this article is to 
discuss some of the problems and tradeoffs I faced in the process. 
Here is an abbreviated version of a summary sheet like that used 
by Kurt Schmucker in Object-oriented Programming for the 
Macintosh. 
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ObjectFORTH 
Background Information 


Programming Environment : MACH2 FORTH 


Toolbox Access : Yes 
Object-Oriented Information 

Instance Variables and Methods : Yes 
Class Variables and Methods : Yes 
Multiple Inheritance : No 
Unique Instance Methods : Мо 
Number of Classes in library : 1 
MacApp access : No 
Dynamic Objects : Мо 


First, let's clarify some jargon used іп the literature. Objects 
are an abstract construct composed of a data structure and 
associated procedures. Objects are organized into child-classes 
of a root class, each child-class having more specifically defined 
methods and data structures than its parent-class. For example, 
"stacks" are a child-class of “ordered lists" which are a child- 
class of "arrays". Each class is composed of instances of the 
class. For example, a particular stack can be an instance of the 
Class "stack". Anobject's data structure consists of named fields 
called instance variables. The procedures are called methods and 
are like subroutines. A program requests an object to execute a 
method by sending the object a message which is used by a 
"selector" routine to select the appropriate method. The set of 
messages to which an object responds is called a protocol. 

There are two essential features of object-oriented program- 
ing, encapsulation and inheritance. Encapsulation refers to the 
isolation of an object's data and methods from other parts of the 
program. Encapsulation is enforced by restricting access to an 
object's data or procedures to a standardized message interface 
used by each object. Objects are presented a message to which 
they respond by selecting a method to execute. The specific 
method is an internal matter for the object and depends on the 
implementation. For example, a link-list can be implemented as 
an ordered array or an unordered array with pointers. The 
importance of encapsulation is that a user of an object does not 
need to know how the object is implemented. In a sense, 
encapsulation is nothing more than a strong form of good 
modular programming practice. However, object-oriented pro- 
gramming not only enforces modular code but also bundles the 
data structures with the procedures. 

Inheritance refers to the ability of objects in a child-class to 
inherit the structure and procedures of the parent-class. Further- 
more, objects in the same class, called instance objects, share the 
same code. The advantage of inheritance is that data structures 
and procedures can be reused and extended. 

In addition to meeting the above requirements, I also had 
several design goals for the extension. The most important 
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influence on the extension described here is its pedagogical 
nature. I was trying to learn about object-oriented programming 
from the extensions and so I made the logical and physical data 
structures as similar as possible. The logical structure adopted is 
that given in Cox's book and is a natural choice for a FORTH 
programmer because of its reliance on linked lists. 

А second design goal was to enforce a strong degree of 
encapsulation by requiring messages to be simple character 
strings, without any procedural capability of their own, and by 
hiding all forth words which identified methods or instance 
variables. Thus, trying to execute the name of a method or 
instance variable will only get you a beep and a question mark. 
An alternate approach is to have method names put an identitier 
on the stack and then have the object use that identifier to find the 
appropriate method. A disadvantage in this approach is that 
forgetting to use the object does not immediately result in an 
error. À disadvantage of my approach is that it requires rather 
major surgery on the links of the dictionary, arisky process which 
slows compilation. 

A third design goal was that every construct in the extension 
should be an object in its own right, each object searching the 
input stream for a message. This means that the creation of 
subclasses is a method of a parent-class object. As a conse- 
quence, objects are divided into two groups, “class defining 
objects", CDO’s, and "instance objects", IO's. Instance objects 
are members of a class that is defined by a class defining object. 
CDO’s are the factory objects of Brad Cox, their main purposes 
are (i) specify the data structure and methods that define the class 
and are used by instance objects, (ii) make instance objects, and 
(Hi) create new child-classes. I will discuss each of these 
capabilities in turn. 

The data structure and methods of an object are implemented 
as normal forth words which are sealed from the rest of the forth 
dictionary by redirecting the links of their headers, more on this 
later. Access to the data structure and method names is controlled 
by the class defining object. A CDO gives a new instance object 
a pointer to the link list of instance methods and instance 
variables that define the class. 

Only CDO’s can make instances of a class. Each instance 
can respond to a protocol of messages as specified by its class 
definition. For example, if Forth’s “Pstack”, for parameter stack, 
and “Rstack”, for return stack, were defined in an object-oriented 
language then they would both be instances of the class “stack”, 
and as such would respond to the message “pop” because that is 
amessage in the protocol of all instances of “stack”. The instance 
“ Pstack" would contain all the characteristics peculiar to the 
parameter stack, such as data, while the instance "Rstack" would 
do the same for the return stack. The CDO "stack" defines the 
structure of the data contained in the instances “Pstack” and 
*Rstack" and the methods to which these instances respond. 

Only CDO's can create new classes. It is the creation of 
child-classes that implements the inheritance of methods. А 
child class inherits the methods and data structure of its parent- 
class. Forexample, “stack” isachild-class of the class “list”, thus 
“list” passes along its data structure and methods to its child-class 
“stack”. Consequently, if instances of “list” respond to the 
message “size”, instances of the class “stack” also respond to 
*size". If the programmer wants instances of the class "stack" to 
respond to "size" in a different manner than instances of the 
parent-class “list”, then the “size” method must be overridden by 
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specifying a new method for the message “size”. This sounds 
great in theory, but practice reveals one of life’s tradeoffs. Take 
our example, one could code a “size” method which works 
ineffieciently for all possible child classes, or one could code a 
method which is optimized for a “list” type object and later 
override the “size” method with one which is optimized for a 
stack type object. The class creation procedure also provides a 
way to add additional methods to the child class, such as “pop” 
for the “stack” class. 

There are important advantages to requiring all constructs to 
be objects. An obvious advantage is the uniform handling of 
objects. Making instances and subclasses is just the same as 
accessing data in an instance object. A much more important 
advantage is that instance and child-class creation are methods, 
methods which can be be overridden by child-classes. In a 
previous example it was pointed out that the “size” method of a 
parent-class can be overridden by the child-class, similarly, the 
instance and child-class creation methods can be overridden. 
This ability to override the methods of a class defining object is 
analogous to the extensibility of the forth compiler, and has the 
same importance. One of the code examples shows the use of this 
feature to alter the instance creation method so that it forms 
instances of variable size. Another example uses this feature to 
implement a C-style data structure. 

A fourth design goal was to make the compiled code as fast 
as possible. Slowness has been a criticized characteristic of 
object oriented languages, although the speed sacrifice can be 
quite small (see Cox’s book for a discussion and references 
regarding this issue). The desire for speed led to a binding 
scheme like that used by Pountain. Binding refers to the point in 
time when a label is associated with a value. For example, the 
definition * : myDUP [7 DUP EXECUTE ; “ would bind early 
the CFA of DUP to the label myDUP. On the other hand, the 
definition “ : PLEASE ' EXECUTE ; “and used as PLEASE 
DUP would be an example of late binding of the label PLEASE 
tothe CFA of DUP. My extension uses early binding in the sense 
that methods are chosen at compilation time rather than run time. 
It uses late binding in the sense that variable names are associated 
with addresses at run time. The essential overhead involved with 
this approach is that a reference to any object instance variable in 
a method definition requires a number to be read off a special 
objectstack and added to an offset number on theregular FORTH 
parameter stack. Any implementation of a data structure as 
complex as an array would require adding some offset value, so 
the extra fetch from the object stack is the actual overhead. Please 
see Pountain's book fora discussion on the whether this overhead 
is worthwhile. 

Finally, a fourth design goal was to make the extension itself 
use abstract data structures in order for the code to be as easy to 
change and maintain as possible. Thus, the data structures in 
class defining objects are accessed by their names as much as 
possible, not by calculating an offset which requires unchanging 
knowledge of the format of the data structure layout. The only 
fixed address is the field used by a CDO to store the LFA of its 
first method, this variable must be in the first long word of a 
CDO’s data set. А consequence of this goal is that the code 
sometimes uses the trick of temporarily pushing an object's 
addresson the object stack and then popping it off when no longer 
needed. 
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Syntax and Usage 


This section describes the syntax used to send an object a 
message, create a new class, and make an instance of a class. 
Additionally, I describe some of the built-in methods and tips on 
using ObjectFORTH. 


en obj m 
Object.1 Msg 
Messages cannot be larger than 32 characters. Capitaliza- 
tion matters! These restrictions are due to the simplicity of the 
selector routine used to find methods. 


Make an instance with the identifier INS.1: 
CLASS.1 Make.Instance  INS.1 


Make.Instance is a method of the class defining object 
CLASS.1, it simply uses the character string INS.1 from the 
input stream to create a dictionary header for the new instance. 


Create new class with the identifier CLASS,2: 
CLASS.1 Define.Child.Class 


‘Class 

І.Уаг <name.1> 
Hide 

:М <name.2> <normal forth def> ; 
‘Class 

k Constant <con.1> 

. Variable <var.1> 

Instance 

Variable «var.2» 

l. Var «name.3» 

n Ins.Array <пате.4> 
Hide 

: M <name.5> «normal forth def» ; 
‘Instance 

CLASS.1 Name.Child.Class CLASS.2 


Each CDO has two sections, a class section which contains 
the methods and variables of the object and an instance section 
which holds the methods and data structure for instances of the 
class. The words :Class and ;Class start and end definition of 
the class section of a child class, similarly for :Instance and 
‘Instance. Each of these parts of the definition are optional. 
Thus, most CDO’s have no need to add methods to the class 
section of the object. The order of the class and instance section 
definitions does not matter. 

The word l.Var creates a long word integer variable which 
is inherited by each child. That is, an |.Var in the class section is 
inherited by any CDO which has CLASS.2 as an ancestor, and 
ап l.Var in the instance section is inherited by each instance of the 
class defined by CLASS.2 and by each instance that has 
CLASS.2 as an ancestor. The word Ins.Array is similar but 
creates an array of n bytes. :М starts the definition of an object 
method. In this example, :M defines a new class method named 
<name.2>. The method <name.2> is used by sending the 
message <name.2> to the object CLASS.2. 

The word Hide prevents previous words in a section from 
being available as methods. For example, use of Hide in the class 
section prevents the <name.1> instance variable from being 
available as a method name. In this way the user of an object 
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cannot gain direct access to the memory location of <name.1> 
by sending <name.1> as a message. Hide is usually used in this 
way, to hide an object's data structure, but it can also hide 
methods. Thus, one could define a method before Hide and it 
would not be available as a public method, only internally to the 
object. Hide is optional. 

Note that normal forth constructs, such as Constant, can be 
used in the definition. How these constructs are used depends on 
their placement. If placed outside the section defining words 
CClass and ;Class or :Instance and ;Instance), such as 
<СОП.1>, then the word is not available in any fashion after the 
object definition is completed. But the word can be used in 
method definitions. This is a good way to define words used in 
method definitions but which are not subsequently desired as 
methods. This should be contrasted with the effect of Hide 
discussed above. For example, the variables «var.1» and 
<уаг.2> both provide a" class variable" for CLASS.2. (Class 
variables are variables shared by instance objects of the same 
class, which сап be used for passing data between instances.) The 
difference between the two is that «var.1» is not available to 
descendents of CLASS .2, while <var.2> would be available to 
new methods of CLASS.2 descendents. That is, methods 
defined in children of CLASS.2 could use «var.2» as a variable. 
However, «Var.2» is not passed on to a child class in the manner 
of an instance variable. If forth definitions are placed inside the 
section defining words but after Hide then the construct is 
available as a method by its name. 

There is an additional method included in the root object 
besides child-class and instance defining methods. This method 
is Describe which describes the an object. This method works 
for both CDOs and instances, but produces somewhat different 
results in each case. In the CDO case Describe prints the name 
of theobject, some information about the object, then sends itself 
the messages Pr.ob.ivar, Pr.class.meths, and Pr.ins.meths. 
These methods list the ivars, class methods, and instance meth- 
ods, however, only Pr.class.meths and Pr.ins.meths will work 
for child objects. Pr.ob.ivar will not work for a child object 
which adds ivars. This example demonstrates one of the subtle 
features of programing with objects. It takes extra thought, and 
sometimes is impossible, to define a method that works properly 
with child classes. 

There are several important features of Object FORTH that 
affect usage. First, the data hiding and encapsulation are accom- 
plished by redirecting links in the LFA of a name header. This 
hiding will be defeated and inheritance will not be implemented 
properly if HASHING is used. Thus, you must turn off the 
HASHING feature of MACH2. Second, only those methods 
which have been declared GLOBAL can be used outside a code 
segment, even interactively. In this regard we are very fortunate 
in the way MACH2 implements NEW-SEGMENT. MACH2 
maintains a separate link list of words which are to have jump 
table entries, then during execution of NEW-SEGMENT this 
link listis traversed, changing the SegmentField of the dictionary 
header to the appropriate number and putting the jump table 
offset into the Parameter Field Pointer region of the dictionary 
header. Thus, those words designated as GLOBAL will have a 
correctly defined dictionary header after NEW-SEGMENT. 
However, the other methods have been delinked from the normal 
search order, so the dictionary header of these words is not found 
and changed by NEW-SEGMENT. What is needed is a new 
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NEW-SEGMENT, а task which remains for the future. Third, 
you must execute Init.Ostack each time you start 
Object.FORTH from a file which was created by NEW-SEG- 
MENT. Also, you must make Init.Ostack part of the initializa- 
tion procedure in a TURNKEY'ed application. The reason for 
this is that the object stack, to be described later, is based on the 
variable Ostack and must be initialized to the proper value 
before use by objects. You have been warned, this one will sting 
you at least once! 

Those familiar with other object oriented languages may 
have noted the absence of SELF and SUPER. These pseudo 
objects are avoided here in preference for the natural Forth ability 
to call any previously defined word. If you're not familiar with 
these SELF and SUPER then ignore this paragraph. 


Implementation 


I will describe the implementation by sequentially discuss- 
ing the most important words in the accompanying code. But 
first, it is best to describe the general structure of the implemen- 
tation. Figure 1 shows the links between words before and during 
the definition of the instance part of a class defining object. It is 
supposed that the class part of the root object OBJECT has 
instance variables C.ivar.1, C.ivar.2, and methods C.meth.1, 
and C.meth.2, while the instance part has variables l.ivar.1 and 
methods I.meth.1 and l.meth.2. CLASS.1 is a child class of 
OBJECT, it has a class part with variable C.ivar.2 and method 
C.meth.3, it has an instance part with variable l.ivar.2 and 
methods |.meth.3 and l.ivar.4. CLASS.2 is а child class of 
CLASS.1, it only has one class method of C.meth.4 and one 
instance method of |.meth.5, no variables. The words word.1, 
word.2 and word.3 are normal forth definitions. 

The left side shows the links before creation of a new child 
class begins. The solid lines represent the links followed by the 
forth interpreter, thus an execution of WORDS would result in 
CLASS.2 word.3 CLASS.1 word.2 OBJECT word.1 etc. 
The dashed lines represent internal links of an object. Data fields 
in the class defining object control access to these link lists. For 
example, an instance of CLASS.1 would use the pointer in a field 
named ins.Key to find the head node for its link list of methods, 
atI.meth.4. This link list of methods would then be traversed by 
a routine called Selector searching for the appropriate method. 
If the search got as far as «root», whose link is zero, then the 
method is not found and an error message is reported. Similarly, 
a field named class.Key points to the head node of methods (i.e. 
C.meth.3) for the class defining object CLASS.1. Inheritance 
is implemented by linking methods of child classes to the 
methods of parent classes. It is also easy to see the effect of Hide. 
In the example all the instance variables are hidden by directing 
the link of the last method of each object to the first method of its 
parent object. That way Selector won't find the method or 
instance variable name. 


The right side shows the links during the definition of the 
instance part of the new class defining object. Two types of 
changes have occurred. First, Define.Child.Class makes a 
change which is not shown, it relinks the section defining words 
‘Class, ;Class, :Instance, ;Instance, and Hide, so that they 
can be used during the class definition. Second, :Instance 
changes the links shown in heavy lines. For each ancestor object 
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there are two link changes which must be made. First the object 
name is linked to the head instance method, for example, 
CLASS.1 in linked to І.тейһ.4. Second, the tail instance 
method is linked to either (i) the next public word (as with 
l.meth.5 to word.3) or (ii) the first hidden word (as with 
l.meth.3 to l.ivar.2). The difference occurs between those 
objects that do not have a hidden part, such as CLASS.2, and 
objects that do have a hidden part, such as CLASS.1. In the case 
of CLASS.1 the last hidden word is already linked to the next 
public word (i.e. l.ivar.2 is linked to word.2). In the case of 
CLASS 2 there is no hidden words so the last unhidden method 
is linked to the next public word (i.e. l.meth.5 is linked to 
word.3). For the root object the next public word is defined to 
be Ob.Words. At the conclusion of defining the instance part 
Instance will return the links to their previous condition. Then 
it only remains for Name.Child.Class to delink the words 
:Class, ;Class, . .. Hide. 

The memory location for each type of object is quite 
different, but each object has a data structure starting at an 
address stored with the name of the object. I call this address the 
data field address, DFA. Thus, the DFA is the address where the 
object's data structure starts. The data structure of a CDO is 
stored along with the dictionary headers, while the data structure 
of instance objects is stored in the Forth code segment by a 
standard ALLOT statement. The reason for this difference is that 
the data for a class defining object is only needed during compi- 
lation and can be disposed when compilation is complete. This 
is automatically done by TURNKEY. The name of a class 
defining object only stores the handle (not a pointer) to its data, 
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whereas the name of an instance object stores the actual instance 
data. The only physical constraint on the data of a CDO is that 
the instance variable class.Key (which contains a relative ad- 
dress pointer to the first class method) must be at a zero offset 
from the value pointed to by the contents of the handle. 

Now let's look at the code. First comes the memory 
allocation for the object stack, enough to accommodate nested 
objects to 20 levels. Ob.DefWords and ObjectFORTH are 
markers which are used by Define.Child.Class to relink and 
delink the words in between. The section defining words :Class 
etc. are deferred so that their definitions can use the data structure 
names defined for the root object. Next come global variables 
used in the construction of new objects. Then the object stack 
manipulation words are defined. Note that the push and pop 
words contain one line of code for error checking which can be 
removed after debugging. Ins.Array, |.Var, and l.Pntr are 
defining words used to define an objects data structure. Let's use 
PFA as one would for an indirect threaded Forth, i.e. PFA is the 
address put on the stack before execution of the DOES» code. 
Ins.Array creates an immediate word that takes an offset value 
from its PFA, compiles it as a literal, then compiles a JSR to 
Осор+. The created word is the name of a variable or array. 
Ins.Array keeps track of the offset to the data for each new 
variable name in the variable Offset, which is incremented by the 
value ‘size’. |.Var is a special case of Ins.Array. |.Pntr is а 
special defining word that doesn't increase the offset value, 
which is useful in constructing variable sized objects, but must be 
used with care. |.Pntr cannot be followed by Ins.Array or |. Var 
or the resulting instance variables will not have the correct offset. 

The method defining word, :M, is nothing more than the 
usual colon definition, but changes could be made in the future. 
For example, :M could look for a duplication of the new method 
and issue a warning. 

А special abort routine is defined. This abort routine is 
turned on by Define.Child.Class and turned off by 
Name.Child.Class. The reason fora special abort routine is that 
acompilation error while a child class is being defined leaves the 
hidden part of the object relinked to the forth dictionary. Unfor- 
tunately, because of the way :Class and :Instance work a 
subsequent attempt to compile the class definition, and conse- 
quent execution of :Class or :Instance, causes the dictionary to 
be relinked in such a way that the first method of the nearest 
ancestor class is the first word searched by the forth interpreter. 
This leads the interpreter to «root» which has a zero link, 
terminating search ofthe context vocabulary and leaving theuser 
shut out from the default Forth words. 

The next group of words are used in connecting messages 
with methods. The most important word in this section is 
Selector. The “Кеу” input argument to Selector is the LFA of 
the first method of an object. Selector then gets the next 
character string in the input stream and uses it to identify the 
appropriate method. Get. Meth finds the method and passes the 
methods CFA to Do.OR.Compile, which executes the method 
If the state is interpret and compiles the word otherwise. The best 
way to understand these words is to first look at Do.Meth. 
Do.Meth pushes the object's data field address, DFA, on the 
objectstack, then execute the method's CFA, and finally pops the 
object stack. Compile.Meth compiles code which does the same 
thing at run time, except that it compiles a JSR to the method. 

The actual definition of OBJECT begins with 
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Ob.Words,which is used by :Class and :Instance to relink the 
previous words so they are visible by the Forth interpreter. 
«root» acts as a null СОО or a stopper for method link lists by 
setting its LFA to zero. «root» acts like a CDO by having а. 
handle to data in the name area that is set to zero. The variable 
#¢.Pvt.Tail is initialized to what eventually will be the CFA of 
the last word in the hidden class part of OBJECT. Offset is 
initialized tozero. All of the instance variables used by OBJECT 
are then defined and Offset is saved in #class.Size for later 
storage in ОВЈЕСТ data structure as class.Size (Remember 
that Offset is used by the variable defining words, such as І.Уаг 
to accumulate the size of the instance object’s data set.. 

The next four words are used in class methods but are not 
available as methods. SetClassStruc, the most important, 
initializes the data structure of child classes. It is defined here so 
that it can use the variable names defined by the previous І.Уаг 
definitions. In order for the link changes to work after execution 
of NEW-SEGMENT all LFA’s must be converted to a relative 
link address, RLA, from a dictionary base pointer. A call to 
ClassStrucAllot with argument #class.Size gets the necessary 
space in the name area. ClassStrucAllot is set up to leave an 
error message but this feature is not implemented yet. After the 
space is allocated the returned address is duplicated. One copy 
is converted to a relative address and stored in the next memory 
location as a handle, the other copy is pushed onto the object 
stack. With the new object’s DFA on the object stack the instance 
variable namescan be used to store the needed data. For example, 
the LFA of the head method for the class defining object is 
fetched from the variable #c.Head, converted to a RLA and 
stored in the field called class.Key. Further explanation of 
SetClassStruc is best done along with a discussion of the 
Define.Child.Class and Name.Child.Class, below. Next, the 
variable #c.Pub.Tail is initialized. This mimics the action of 
Hide. 

The words Pr.ob.ivar, Pr.class.meths, Pr.ins.meths, and 
Describe are methods that can be used to describe a class 
defining object. As discussed earlier, Pr.ob.ivar only works 
with OBJECT, it won't print any new instance variables in a 
child class. 

The nextthree methods are the most important. The first two 
control the creation of child classes and the third makes instances 
of the class. Their use was described in the syntax section. 
Define.Child.Class initializes temporary variables used during 
the definition of a child class. Name.Child.Class actually 
creates a new child class, it sets up the data structure, seals the 
object so that the Forth interpreter cannot find its methods or 
variable names, links the tail method (which is the first method 
defined for a child class and the last one in the search order) of 
each part (classor instance) of the object to the head method (first 
in the search order) of the parent class and delinks the section 
defining words. Lets examine these methods, along with 
SetClassStruc and the as yet undefined words :Class and 
;Class. The words :Instance and ;Instance behave similar to 
:Class and ;Class, so are not discussed. 

Please examine each step in Define.Child.Class, in most 
cases the value contained in an instance variable of the object 
executing the Define.Child.Class method is stored in a tempo- 
rary variable. In three cases an RLA is converted to aLFA. The 
LFA of the most recently defined public forth word is saved in 
#Forth.Head for use by the SetClassStruc routine. Saving 
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class.Size, ins.Size, сіа55.Кеу and ins.Key implements the 
inheritance feature of object oriented programming. The vari- 
ables #с.РМ.Тай thru #i.Pub. Tail are set to zero to flag the use 
or not of the section defining words :Class and :Instance. The 
variable #parent is set to the relative DFA of the objectexecuting 
Define.Child.Class. The words :Class etc. are relinked to the 
dictionary and the custom abort routine is installed. This com- 
pletes the setup, we’re now ready to execute :Class or :Instance. 

Class has two types of actions. First, it initializes certain 
variables. The size of the class defining object’s data structure 15 
obtained from #class.Size and stored in Offset, remember that 
words like L Var use the variable Offset. Тһе variables 
#c.Pvt.Tail and #c.Pub.Tail are initialized to the same value. 
Each holds the future CFA of the tail word in the class section of 
the new object. This is converted to an LFA later. The variable 
С.ог.12 is set to flag that compilation is inside the class section 
of the new object. The second type of action is to relink all 
ancestor class methods to the dictionary by executing 
Relink.Parents. Note that :Class is not a method, so it doesn’t 
have access to the instance variables of the object which executed 
Define.Child.Class. 

Relink.Parents is one of the most difficult words in the 
entire code. It begins by pushing the DFA of the object executing 
Define.Child.Class (stored in #parent by 
Define.Child.Class) on the object stack in order to use instance 
variable names in the definition. Next, it checks the С.ог.1? flag 
and then branches to the correct loop. The Begin-Repeat loop 
relinks each ancestor object and exits when it reaches an ancestor 
object with a class.Key of zero, an event which occurs when 
relinking reaches the null object «root». The following is 
executed for each ancestor object, say Ob(i). If class.Key is not 
zero it checks class.Tail to see if Ob(i) has a class section. The 
instance variable class. Tail contains the value of #c.Pub. Tailat 
the time SetClassStruc was executed during the definition of 
Ob(i). Remember, #c.Pub.Tail is set to zero by 
Define.Child.Class and it is changed to non-zero by :Class. 
Thus, class.Tail is zero if the Ob(i) has no class section, and is 
non-zero if Ob(i) has а class section. 

If there is no class section of Ob(i) then no relinking should 
be done. In this case Relink is skipped, the next object’s DFA is 
calculated from the contents of ivar Parent, the old DFA is 
popped from the object stack, and the new DFA is pushed on the 
object stack. Thus, when the loop starts again with a fetch of 
class.Key it will operate on the parent of Ob(i). In the case that 
class. Гай is not zero then relinking must be done. The current 
value of the objects LFA is stored in the ivar Ob.name.link for 
future restoration. Then, the offset to the head class method is 
stored in the LFA of ОЫ(і). Finally, the contents of the tail 
method’s LFA are swapped with the value in Cc. Tail.link. 

Hide can be used during the definition of a class or instance 
section. Hide simply resets# c.Pub.Tail, if defining a class 
section, or #i.Pub.Tail, otherwise. This makes #c.Pvt.Tail and 
#c.Pub.Tail different, so that later one can tell if Hide was used. 

The word ;Class has two parts. The first part stores the LFA 
of the head class method in the variable #с.Неаа, saves Offset 
in#class.Size, and converts the CFA of the words pointed to by 
#c.Pvt.Tail and #c.Pub.Tail to LFA’s. Remember that these 
two values are different if the word Hide was used to hide some 
of the methods or instance variables. The second task of ;Class 
is to delink the ancestor objects. This process is essentially the 
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inverse of the relink process except that the contents of 
class.Key are not needed, because the original contents of the 
objects LFA were stored in Ob.name.link. 

Name.Child.Class actually sets up the new object. First, it 
delinks the words :Class etc., restores the normal abort routine, 
creates an immediate name for the new class defining object, and 
then enters SetClassStruc. The SetClassStruc routine has 
been partially explained. Now let’s examine the handling of 
с. Тай ИК and i. Tail.link, which, as we have seen, each store the 
required link change for the tail unhidden method of each section 
of the class defining object. Let's consider c.Tail.link as an 
example. Recall that only two links need to be changed by 
‘Class. The second link change requires that the tail unhidden 
method be redirected to the first hidden word, if there is one, or 
the next regular public Forth word, otherwise. Which specific 
change to make is determined at this point and stored in the field 
c.Tail.link for later use. Тһе variables #c.Pub.Tail and 
itc.Pvt. Tail contain the LFA of the tail unhidden method and tail 
hidden method, respectively. If there is a hidden part then the 
contents of #c.Pub.Tail and #с.РМ.Тай will not be the same, 
(because of the action of Hide.) so c. Tail.link should be set to the 
default contents of the tail unhidden word's LFA, i.e. to the 
contents of the address pointed to by the contents of #c.Pub. Тай. 
If the contents of #c.Pub. Tail and #c.Pvt. Tail are the same then 
there is no hidden part (Hide has not been used) and the offset to 
the next public word is calculated (using #Forth.Head) and 
stored in c.Tail.link. Finally, notice that if the new object has no 
class section (specifically, if ;Class was not executed.) then 
#c.Head contains the LFA of the head class method of the parent 
class, which is stored in the class.Key field. Similarly for 
#i.Head and ins.Key. 

The final task of Name.Child.Class is to seal the object and 
link it to the parent object. Alteration of the links occurs in the 
two IF-THEN parts of Name.Child.Class. If there аге no 
additions to methods or instance variables in the class part of the 
new CDO then no link changes should be made. Determining 
whether there has been additions or not is made by examining 
itc.Pub.Tail (stc.Pvt.Tail would work just as well), which was 
set to zero by Define.Child.Class and would only be non-zero 
if :Class were executed during the child definition. The order of 
execution inside the IF- THEN part is important. First the tail 
hidden word in the class part, probably an instance variable, is 
linked to the most recently defined public word in the dictionary. 
Second, the tail unhidden method is linked to the head method of 
the parent class to implement inheritance. If there is no hidden 
section, because Hide was not used, then the second step just 
overwrites the first step because Яс.Рир.Тай and #c.Pvt.Tail 
will contain the same number. Link changes in the instance part 
of the new class defining object are handled similarly. 

The DOES» code of aclass defining objectis different from 
that of an instance object because its data is in the name area. The 
handle toa class defining object's data is stored in its PFA, so the 
DOES?» code is a fetch to get the relative address of the DFA, 
calculate the DFA, a dup and fetch to get the RLA of the head 
class method. 

The Make.Instance method is simple by comparison. It 
creates an immediate name, stores the RLA of the head instance 
method in the next long word, and allots enough space for the 
instance data structure. The DOES» code simply duplicates the 
PFA and fetches the RLA of the head instance method, convert- 
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ing it to the LFA. 

The definition of data structure and methods for instances of 
OBJECT are similarly defined. The only default methods 
provided аге those useful in describing an instance object. Notice 
that, as with the class section, an important control variable, 
І.Кеу, is defined as a regular instance variable. This means that 
one could use this variable in methods, or even change its value. 
However, this is very dangerous since this variable is the link 
from between an instance and its class defining object. Changing 
this pointer can have disastrous results. 

This essentially completes the definition of OBJECT. The 
actual construction is done by :OBJECT. There are a lot of 
references to specific names or addresses in these procedures 
because OBJECT is the first object. 


Examples 


The file concludes with several example objects. The first 
example is that of a simple integer object. Each instance of 
Integer can hold one long word integer and has the messages 
Save and Fetch. It is clearly very inefficient compared to the 
standard VARIABLE defining word. The second example shows 
how to define a fixed size array class of 10 cells. 

The third example allows variable size array objects to be 
defined and shows the power of being able to redefine the 
Make.Instance method. This example also demonstrates use of 
the І.Рпг defining word. As mentioned earlier, this word must 
be the last instance variable and no child class may add instance 
variables. Thus, the instance variable Length is defined here, 
although it is not used by instances of Array, in order to be used 
by instances of a child class of Array. Be careful with this word! 
The next two examples use the variable array object to define a 
Vector object and a String object. Error checking has been 
implemented, but otherwise the objects are very primitive. 

Finally, the example object Struct can be used to define C- 
style data structures. Again, it shows the power of being able to 
redefine the Make.Instance method. Note that even the 
DOES» code of Make.Instance has been changed. Also notice 
that the words S.Array and Longlnt are instance variable defin- 
ing words like Ins.Array and l. Var. These words must be defined 
in the instance section in order to be available to define the 
instance section of child class objects. These words cannot be 
used during definition of a child's class section, one needs to use 
the regular instance variable defining words. 


Improvements 


There are several areas in which this code can be improved. 
The mostobvious need is for assembly coding of the object stack 
control words, especially the word Осор+ since it represents the 
execution overhead for fetch and save operations on instance 
variables. It would be nice to give the object stack its own CPU 
register. Unfortunately MACH2 does not leave any untrashable 
registers for applications, unless one gives up local variables by 
using A2. Second, there are no dynamic objects, although the 
Mac's heap would make implementation relatively easy. Third, 
I have not included words to accommodate floating point num- 
bers. Fourth, the error handling is rather primitive. Etc. 

Caveats 

I have tried to use this code as much as possible before 

publication. However, there certainly are combinations I have 
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not yet tried. So, let the user beware. I would appreciate hearing 
about any suggestions, bugs, or improvements. My mailing 
address is Wayne Joerding, Department of Economics, Wash- 
ington State University, Pullman, WA, 99164. 


Listing 1: Object Forth for Mach2 
\ ObjectFORTH.9 bu 
N Waune Joerding 
\ S.E. 430 Dilke St. 
\ Pullman, МА 99163 
\ Copyright 1988 by Wayne Joerding for MacTutor 


only mac 
8150 forth 


$4EBA CONSTANT JSR. dCPC) 
%4Е75 CONSTANT RTS 


$203C Constant МОМЕ. 8/00 
$4 IFBÜBFA Constant (ҒА %-6(РС,00.12,А0 
$2008 Constant МОМЕ. А0,-(Аб) 


: Defer .Not. Init 
: Defer 

Create -4 ALLOT JSR.dCPC) W, 

(71 Defer.Not.Init HERE - W, RTS N, 


." Uninitialized^ abort ; 


: Let: С - cfei2 ) 62%: 


: 00: C cfa - ) ' over - swap W! ; 
\ ==== Ор jectFORTH ЕЕЕЕБЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕ Е 
20 4 * CONSTANT Maxnest 


VARIABLE Ostack 


V — Allocate space for Object Stack - 
Ostack 4 * maxnest * Ostack ! maxnest Vallot 


GLOBAL 
: Init.Ostack Ostack 4 * maxnest * Ostack ! : 


, 


\ 
CREATE ObjectFORTH 


N — Section defining words 
GLOBAL Defer :Class 

GLOBAL Defer :Instance 
GLOBAL Defer ;Class 

GLOBAL Defer ; Instance 
GLOBAL Defer Hide 


CREATE 0b.DefWords 


GLOBAL 

CODE DictBaseé (C-n) 
MOVE.L $-532(A5),-CA6)RTS 
END-CODE MACH 


: Relink.DefWords 
[ ° Ob.DefWords body»link dup 6 swap 
DictBase8 - swap 1 literal literal DictBaseé + ! 


: Delink.DefWords 
[ * Ob.DefWords body» link ' ObjectFORTH 
body) link over swap - swap DictBase@ - swap 1 
literal literal DictBaseé + ! 


; 


Y ==== Global Variables for Class Definition === 
VARIABLE *class.Size 
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VARIABLE #ins.Size 
VARIABLE "Forth .Head 
VARIABLE #c.Head 
VARIABLE #c.Pub.Tail 
VARIABLE #c.Pvt.Tail 
VARIABLE #1 .Head 
VARIABLE *ti.Pub.Tail 
VARIABLE t i.Pvt.Tail 
VARIABLE *parent 
VARIABLE 8C.or.1? 


\ ====== Object Stack =========================== 
GLOBAL 
: Opush Сп — ) N push from Pstack to Ostack 
Ostack dup @ 4 - = 
IF .” Ostack overflow" abort THEN 
Ostack -4 over +! @ ! 


7 


GLOBAL 

: Opop ( - ) \ discard top number on Ostack. 
Ostack dup maxnest + 4 + swap 8 = 
IF .^ Ostack underflow” abort THEN 
4 Ostack *! 


д 


GLOBAL 
: Ocopt Сп - ntos ) \ add Ostack to Pstack. 
Ostack @ @ + 


д 


GLOBAL 
: Осор C - os 2 N copy Ostack to Pstack. 
Ostack ё e 


2 


V ==== Data Structure Defining Words ============= 
GLOBAL VARIABLE Offset 


GLOBAL 

: Ins.Array С size - ) С name -IN- ) 

X Маке а new instance variable of ‘size’ bytes. 
СРЕАТЕ immediate 


Offset 6, N store offset 

dup 2 mod + N make sure even number 
Offset +! N increase offset 
DOES» С ob.DFA -05- ob.DFA 2 


6 (compile] literal 
compile Ocop* 
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GLOBAL 

: I.Var С - 2 C name -IN- ) 
4 Ins.Array 

GLOBAL 


: L.Pntr С- 2 С name -IN- 2 
X Meke ivar without incrementing. 
CREATE immediate 
offset 6, N compile offset. 
DOES» С ob.DFA -05- ob.DFA 2 
6 (compile) literal 
compile Ocop* 
; 
\ ==== Method def ining word ======================= 


GLOBAL 
: :M( — ) N Define a method. 


80 USER (ABORT) 
VARIABLE “ABORT 
: Ob.Abort ( n - ) N Use during class definition. 
ЯС.ог.17 ё сг 
IF .? Class part” ;Class 
ELSE .^ Instance part” ;Instance 
THEN 
“ABORT @ CABORT) ! ABORT 


\ ЕЕ Message support БЕРЕЕЕЕБЕЕЕЕЕЕЕЗЕЕЕЕЕЕЕЕЕЕ 
: link»name 4 + ; 
: Compile.Meth C meth.CFA ob.DFA - 2 


the following line was edited out - JL 
[compile] literal V маке а literal of ob.DFA 


ем — — — = 


and replaced bu the following four lines 
MOVE 1 8/00 W, 

here - т 

(ЕА-%-6(РС,0012,А0 , 

MOVE .L_A®, -CA6) W, 


compile Ори$һ V compile a call to opush 
JSR. dCPC) W, here - W, 
compile Opop 


J 


: Do.Meth С meth.CFA ob.DFA - ) 
Opush execute Opop 


2 


: Do.OR.Compile С ob.DFA meth.CFA fo – ) 
1 z 
IF swep Do.Meth 
ELSE 
swap state 6 
IF Compile.Meth 
ELSE Do.Meth THEN 
THEN 


2 


GLOBAL 
‚ Find.Meth? 
(fa strng.adr | f — strng.adr CFA fo) 
Vf = as with FIND 
0-f 


BEGIN 
lfa link^?name Ce $11111 and 
strng.adr C8 = 


IF 1-» f strng.edr Сё L_ext 1+ 1 
DO strng.adr І + Сё lfa4 +I + Ce o 
IF Ø -> f leave THEN 


f 0= lfa @ ð © and 

WHILE — XV continue if meth € message & (ҒАОЙ 
lfa ё negate +> Ifa 

REPEAT 

strng.adr f 

IF Ifa dup link?body swap 1іпк› пате Сё 
2100000009 and 
IF 1 ELSE -1 THEN 

ELSE f 

THEN 
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GLOBAL 

: Get.Meth С key strng.adr - meth.CFA ҒОЙ ) 
Find.Meth? 
?dup IF 
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rot drop MOVE.L —A0,-(A6) 
ELSE MOVE.L —*,-(A6) 


cr ." Method  * count 211111 and RTS 
type 3 spaces .” Not Found” ABORT END-CODE 
THEN 
: SetClessStruc С - ) 

GLOBAL 8с1855.5і2е ё ClassStrucAllot 

: Get.Msg ( - strng.adr ) IF ." Memory error” . .” Handle" . abort 
32 word pad over Сё L ext 1+ стоуе pad ELSE 
3 dup DictBase@ - , 

Opush 
GLOBAL 
: Selector С ob.DFA key - ) С «nsg? -IN- ) 8c.Head 6 DictBaseé@ - 
Get .Msg class.Key ! 
Get .Meth #c.Pub.Tail @ dup IF DictBase@ - THEN 
Do.OR.Compile cless.Tail | 
д 
#c.Pub. Tail 6 dup 
IF dup #с.Ру{.Та11 @ = 
CREATE Ob.Words IF #Forth.Head 6 - 
ELSE 6 THEN 

N ==== Define OBJECT ============================ THEN c. Tail. link | 

: :Root ®class.Size 6 class.Size | 
Create N stopper word "i.Head ё DictBaseé - 

NP e DictBaseé - , ins.Key ! 
0 NP e! \ put 0 for class.Key "i.Pub.Teil 6 dup IF DictBase@ - THEN 
4 NP +! \ increment NP by 4 bytes ins.Tail ! 
J #i.Pub.Tail @ dup 
IF dup #i.Pvt.Tail ё = 
:Root «root? IF *Forth.Head ё - 
ELSE @ THEN 
V — Def ine class section of OBJECT —— THEN i.Tail. link | 
here #c.Pvt.Tail ! #ins.Size @ ins.Size ! 
"parent @ Parent ! 
0 offset ! last DictBase@ - Class.RLA ! 
GLOBAL I.Var class.Key last @ ob.name. link ! 
I.Var class.Tail Орор 
І.Уаг c.Tail.link ТНЕМ 
GLOBAL І.Уаг class.Size j 
GLOBAL I.Var ins.Keu 
I.Var ins.Tail here #c.Pub.Tail ! 
I.Var i.Tail.link 
GLOBAL I.Vear ins.Size :M pr.ob.ivar ( - ) 
I.Var parent cr cr .” Class instance variables are :” 
I.Var Ob.name.1]ink cr5sp .^ class.Keu = 
I.Ver Class .RLA cless.Key @ DictBase@ + . 
offset 6 8с1а55.біге ! crosp .^ cless.Teil =“ 
class. Tail @ DictBase@ + . 
: crosp cr 5 spaces ; crosp .^c.Teil.link =” 
c.Teil.link ё . 

: ‹{Рг.Ме{һ› С adr спі - D сг55р .” class.Size =" 
сг55р %11111 and swap over type class.Size 6. 

25 swap - spaces .” Link adr = ” crosp .^ ins.Key =“ 

dup . space .” Offset = " dup ё . ins.Key 6 DictBaseé 

| crosp .^ ins.Tail =" 
ins.Tail @ О1с{Вазе@ +. 

: Pr.meths C key - ) crosp .^ i.Teil.link =” 
BEGIN i.Tail.link e . 

dup 6 crbsp .^ ins.Size =” 
WHILE ins.Size 6. 

dup link?name count crbsp .^ Perent =" 

«Pr.Meth» dup e - Parent 6 DictBaseé + . 
REPEAT drop cr5sp .” ob.name.link = ~ 
; ob.name.link ё . 

CODE ClassStrucAllot ( n - addr ) cr5sp .” Class.RLA =" 
MOVE.L — $- IFCCA52,D0 Class.RLA 6 DictBase8 + . 
MOVE.L 00,01 ; 

ASR.L 8%1,01 GLOBAL 
BCC.S e1 :M Pr.class.meths С - ) 
ADDQ.L #$1,00 cr cr .^ Class methods are :” 

61 MOVE.L 00,А0 class.Key ё DictBaseé + 
ADD.L (A62*,D0 Pr .meths 


MOVE.L D®,$-1FCCA5) 


; 
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GLOBAL 

М Pr.ins.meths С - 2 
cr cr .^ Instence methods are :” 
ins.Key 6 О1с{Вазе@ + 
Pr.meths 


7 


GLOBAL 
:М Describe С – ) 
cr .^ — Class Information 


cr ." NAME : * Class.RLA 6 DictBase@ + dup . 


link?name count #11111 and type 

5 spaces .” pointer to class dete = * Ocop . 
Pr .ob.ivar 

Pr.class.meths 

Pr.ins.meths cr 
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GLOBAL 
“М Def ine.Child.Cless С - ) 
lest "Forth.Head ! 
class.Size 6 *class.Size ! 
ins.Size 6 #ins.Size ! 
class.Key 6 DictBase@ + #c.Head ! 
0 "c.Pvt.Tail ! 
0 *c.Pub.Tail ! 
ins.Key 6 DictBase@ + *i.Head ! 
Ø *i.Pvt.Tail ! 
Ø *i.Pub.Teil ! 
Осор DictBase@ - "parent ! 
Relink.DefWords 
[ * Ob.Abort body» link DictBase@ - 1 literal 


DictBase@ + link»body (ABORT) dup 6 “ABORT ! 


ә 


GLOBAL 
“М Name.Child.Class €(-) ( «name? -IN- ) 
Delink.DefWords 


“ABORT 6 CABORT) ! V restore old abort routine 


CREATE immediate 
SetCLassStruc 


N — seal class and link to parent 
last dup *Forth.Heed 6 - swap |! 


8c.Pub.Teil 6 ?dup V false => no class section 
IF %c.Pvt.Tail 6 dup *Forth.Head ё - swap 


dup class.Key @ DictBase@ + - swap ! 
THEN 


$i.Pub.Tail 6 ?dup V false => no class section 
IF #i.Pvt.Tail 6 dup "Forth.Head ё - swap ! 


dup ins.Key 6 DictBase@ + - swap ! 
THEN 


DOES» 6 DictBase@ + dup 6 DictBase@ + Selector 


7 
GLOBAL 
:M Make.Instance С – ) С «name? -IN- ) 
CREATE immediate 
ins.Key 6, 
ins.Size 6 allot 
DOES» dup 6 DictBase@ + Selector 


д 


lest #c.Head ! 


N —Def ine instance section of root object —— 
here *i.Pvt.Teil ! 

0 Offset ! 

GLOBAL І.Маг I.Key 
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Offset 6 *tins.Size ! 
here *i.Pub.Tail ! 


GLOBAL 

:M Pr.Imeths € - 2 
І.Кеу 6 DictBaseé 
cr cr .^ Instance 
Pr.meths 


GLOBAL 
:М Name С — 2 


+ 
methods are :” 


cr ." NAME : ~ Осор 4 - боду) 1іпк link»name count 


$11111 end type 5 


7 
GLOBAL 
:M Describe С - ) 
cr .” — Instance 
Name 
Pr.Imeths 


2 


lest #i.Head ! 


V — Child Class def in 
: Relink (tok | - ) 


spaces .” instence.DFA = * I.Key . 


information ————————————"^ 


ing words ----- 
С dfa -05- dfa’ 2 


Class.RLA 6 dup DictBase@ + 


dup 6 Ob.name 


„ок ! 


swap К 6 - swap ! 
o @ t e DictBase@ + dup ё о ! ! 


. 
? 


: Relink.Parents С - ) 
parent 8 DictBase8 + Opush 


8C.or.I? 6 
IF 
Begin 


class.Key 6 


While 


class.Tail dup @ 


IF 
ELSE drop 


c.Tail.link class.Key 
Rel ink 


THEN Parent @ DictBase@ + 


Repeat 
ELSE 
Begin 


Орор Opush 


class.Key @ 


While 
ins. Tail 
IF 


ELSE drop 


dup @ 
i.Teil.link ins.Key 
Rel ink 


THEN Parent ё DictBase@ + 


Repeat 
N 


Opop 


: Delik (ot | - ) € 


t @ 
IF 


Орор Opush 


dfa -05- dfa’ ) 


Ob.name. link ё Class.RLA @ DictBase@ + ! 
о @ t ё DictBase@ + dup ёо ! ! 


THEN 


Parent 6 О1с{Вазе@ + 


Орор Opush 


д 


: Delink.Parents С - ) 


parent ё DictBase@ + Opush 


8C.or.I? e 
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IF 

Begin 
class.Key 6 N class.Key is zero for «root» 

While 
c.Tail.link  class.Teil 
Delink 

Repeat 

E 


Begin 
cless.Key 6 N class.Key is zero for «root? 
While 
i.Teil.link ins.Tail 
Delink 
Repeat 
N 


Opop 


7 


: «Class? (-) 
8Sclaess.Size 6 Offset ! 
here #c.Pvt.Tail ! 
here #c.Pub.Tail ! 

-] 8?C.or.I? ! 
Relink.Parents 


Let: :Class Do: <:С1ав5» 


: 6Cles? (-) 
last "ic.Head ! 
Offset 8 'iclass.Size ! 
8c.Pvt.Tail @ род) link %c.Pvt.Tail ! 
8c.Pub.Tail 6 body) link #c.Pub.Tail ! 
Delink.Parents 


Let: ;Class Do: <;Class> 


: € Instence» С - ) 
Sins Size 6 Offset ! 
here *i.Pvt.Tail ! 
here #i.Pub.Tail ! 
0 "C.or.I? | 
Relink.Parents 


Let: :Instance Do: «:Instance? 


: Instance» С - ) 
last 81.Неад ! 
Offset 6 "ins.Size ! 
8i.Pvt.Tail 6 body link ttíi.Pvt.Tail ! 
8i.Pub.Tail 6 body» link #i.Pub.Tail ! 
Delink.Parents 


2 
Let: ; Instance Do: «;Instance? 
: «Hide» 


here #C.or.I? e 
IF %c.Pub.Tail ! ELSE "*ti.Pub.Tail ! THEN 


9 


Let: Hide Do: «Hide» 


\ — Complete and Seal root object 


: : OBJECT 
CREATE immediate \ make header for “OBJECT” 
DOES» 6 DictBase@ + dup 6 DictBase@ + Selector 


4 


:ОВЈЕСТ OBJECT 


\ - Initialize temporary variables used by Set.Struc - 
^ «root? 4 + @ "parent | 
^ Ob.Words body) link #Forth.Head ! 
8Sc.Pub.Tail 6 body» link %c.Pub.Tail | 
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*i.Pub.Tail 6 body link #i.Pub.Tail ! 

8c.Pvt.Tail 6 body» link %c.Pvt.Tail ! 

8ji.Pvt.Taeil 6 body» link #i.Pvt.Tail ! 
SetClassStruc \ init class data structure 
V - seal class and link to «root? 

Del ink .Def Words 

“ «root? body» link “parent ! 

*i.Pub.Tail 6 dup "parent ё - swap ! 

"c.Pub.Tail 6 dup "parent @ - swap ! 

81.Ру(.Та11 € dup *Forth.Head ё - swap ! 

%c.Pvt.Tail 6 dup *Forth.Head ё - swap ! 

0 ' «root? Боду? link 

last dup ' Ob.DefWords body) link - swap 

! ! 


N ====== EXAMPLES ==============:==:== 
\ #===== Integer Class ============= 
OBJECT Define.Child.Class 
: Instance 
I.Ver Int 
Hide 
М Fetch С -n D 
Int e 
М Save ( n - ) 
Int ! 
; Instance 
OBJECT Name.Child.Class Integer 
\ ====== 10 cell Array Class ========55==== 
OBJECT Def ine.Child.Class 
: Instance 
10 Constant Max .Size 
10 4 * Ins.Arrey Head 
Hide 
:M Describe 
cr ." — Instance Information ——— ———————"^ 
Мате 
cr ." Max.Size Cin cells) = * Max.Size . 


Pr.Imeths 


М 

:M Store Сх i - ) 

V Store value x in array for index = i 
Mex.Size over 1 + ‹ if .” index out of bounds” abort then 
4 * Head + ! 


:М Retrieve Ci-) 
\ Retrieve value of array for index = i. 


Max.Size over 1 + < if .” index out of bounds” abort then 
4 * Head + @ 


; 
¿Instance 


OBJECT Name.Child.Class Arraygid (-) 


\ ====== Variable size Array Class =============== 
Integer Define.Child.Class 
: Instance 

I.Ver Max. Index \ mex size of аггау 

I.Ver . Length \ number of elements in array 

I.Pntr Start \ points to the start of аггау memory 
Hide 

:M Describe 

cer .” — Instance Information ---------” 


cr ." Mex Length in cells = * Mex.Index @ 1+. 
cr .” Cell size in bytes =” Int Ө. 
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Pr.Imeths 


) 
:M Store Сх i - ) N Store value x in array for index = i 
N first cell hes index of zero 
Max.Index 6 over < over 0 < or 
IF .^ index out of bounds” abort THEN X <- error checking 
Int ё х Start + | 


4 

:M Retrieve C i - ) N Retrieve value of array for index = i. 
Мах. пех 6 over < over 0 < or 
IF .^ index out of bounds” abort THEN X <- error checking 
Int 6 * Start + e 


7 
;Instence 
: Class 
‚М Make. Instance Спс - 2 C (nene? -IN- 2 
\ Array instance of size n cells, cell size of c 
CREATE immediate 


ins.Key @ 

; V store key to nethods of parent cless 
dup , N save cell size in ‘Int’ variable 
over 1- , N маке and save Max.Index 


Ü, N init current Length to zero 
* ins.Size @ + allot 
DOES» dup 6 DictBase@ + Selector 


;Class 
Integer Name.Child.Class 


\ zzzzzz Vector (lass zszszssszzszzzzzz2222zz222z2z2222zzzz2z2- 
Array Def ine.Child.Class 
: Class 
:M Маке. Instance С n - 2 
4 Meke. Instance 


;Cless 
Array Name .Child.Class Vector (п-) 
\ ====== String (lass ========5================5===Е=Е5Е= 
Array — Define.Child.Cless 
: Class 
:М Маке. Instance С п - 2 
1 Мәке. Instance 


;С1а$$ 
: Instance 
:M Describe 
cr .” — Instance Information ----- 
Name 
cr 5 spaces ." Max String length =“ 
Мах. Іпдех ё 1%. 
сг 5 spaces .” Current String length = * Length 6. 
Pr.Imeths 
д 
:M Print ( - 2. VPrints string for this instance. 


Start Length 6 дир 
IF type ELSE .” string empty^ drop drop THEN 


"М Store С a - ) \Ѕіоге а string with count byte at address. 
count dup Max.Index @ 2 + < 
IF dup Length ! Start swap cmove 
ELSE cr .^ String too large for “Store” * drop drop 
THEN 


д 
; Instance 


Array Name.Child.Class String (n-) 


\ ==== Struc Class ================================= 
OBJECT Def ine.Child.Class 
: Class 
: Make. Instance С - ) С name -IN- ) 
CREATE immediate 
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Ins.Key 6, 

ins.Size 6 allot 

DOES» dup 6 DictBase@ + Get.Msg Get.Meth 
drop execute state @ 
IF [compile] literal THEN 


;Class 
: Instance 
: §.Array С size - ) С name -IN- ) 
CREATE 
offset 6, 
dup 2 mod + 
offset +! 
DOES ё + 


: LongInt С - > € name -IN- ) 
4 S.Array 


7 
¿Instance 
OBJECT Name.Child.Class Struct 
\ ==== Point Class ЕР>РЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕЕ 
Struct Def ine.Child.Cless 
: Instance 
LongInt Xdim 
LongInt Ydim 
; Instance 
Struct Name.Child.Class Point 
Listing 2: Test code for the Mach2 00РЗ extensions 
\ This was on one of Wayne's earlier disks. 
\ I included it here because it still works end makes а nice example. 
\ - Л 
V — testing words 
V - test Integer — 
Integer Make. Instance XY 
XY Describe 


V - test of Arrayid — 
Array ið Make. Instance vec 19 
000 0 уес10 Store 
111 1 уес19 Store 
222 2 уес10 Store 
cr 1 уес10 Retrieve . 

уес10 Describe 


N - test of Array — 

10 4 Array Маке. Instance Arr 
000 0 Arr Store 

111 1 Arr Store 

999 9 Arr Store 

cr 9 Arr Retrieve . 

Arr Describe 


\ - test of Vector — 

10 Vector Маке. [пз4апсе vec 
000 0 vec Store 

111 1 vec Store 

222 2 vec Store 

cr 2 vec Retrieve . 

vec Describe 


V – test of String — 

14 String Make. Instance hello 
hello Describe 

: hel .^ This is hello”; 

‘ hel 4 + hello Store 

cr hello Print 


\ - test of Point — 

Point Make.Instance thisPoint 

111 thisPoint Xdim ! cr thisPoint Xdim 6. , 
222 thisPoint Ydim ! cr thisPoint Үйіп 6. Sel 
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Forth Forum 
Appletalk Mail 


“Appletalk mail for Mach2" 


This month I'll give youa brief re-introduction to Appletalk 
and Mach2 words for Appletalk handling. The example will be 
a set of two programs - a message sender and a message receiver 
which together form a very rudimentary mail utility. 

We've already had some contributions on Appletalk: for 
additional reading see the articles by Bob Denny, V1410 and 
У1#11; Alan Wootton, V1#10; Dave Kosiur, V3#4; and on the 
printer access protocol by Mike Schuster, V2#2 and Nicholas 
Pavkovic, V4#1. Also, for any serious Appletalk programming 
it is indispensable to have a copy of Inside Appletalk handy, and 
the Appletalk chapter of Vols. II and V of Inside Macintosh. 

I thought it worthwhile to write a sample Appletalk applica- 
tion in Mach2 Forth, especially since the Appletalk example 
included in the Mach2 system does not give a hint how to use 
higher level protocols. 


Appletalk protocol levels 

Let’s - very briefly - review the way Appletalk sends data 
over the network. 

We must view the Appletalk cable as a bus to which up to 32 
devices can be attached. The bus is very simple, containing a 
twisted pair of wires, and information must therefore be passed 
along it serially. This serial transfer proceeds at a rate of 230.4K 
baud. The basic Appletalk message unit sent on the bus is a packet 
of data, which can be zero to 600 bytes long. 

Evidently, only one device at a time can send something 
along the bus. If - let's say - a program instructs my Mac to send 
out a packet of data and at the same time the Laserwriter sitting 
in another room tries to send as well, everybody else will receive 
only garbage. The Appletalk hardware has a way of detecting this 
Situation, and will automatically re-send the packet after a 
random wait. This way itis ensured that the two devices probably 
won’t cross-talk again. 


ALAP 

You don’t perceive this mechanism (in network language it 
is called the Appletalk Link Access Protocol or ALAP). If youask 
the Appletalk driver to send out a packet of data, you can be sure 
that - using a transparent handshake mechanism between sender 
and receiver, and a CRC for error checking - it will be sent to the 
correct destination on the local net, or else you’ll get an error 
message. 

Devices are identified on the Appletalk line by their node 
numbers, each device having a different number. The node 
number is assigned automatically when a device first uses the 
network; it looks around for other active nodes and chooses a 
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node number that isn’t used yet. АП this happens та completely 
transparent way. 

Packets sent out over the network are identified by their 
source and destination node numbers, which are contained in 
their header. Detection of the header is done by the hardware, so 
only packets addresses to one node will be noticed by that node, 
anything else on the bus will be ignored. 


DDP 

A destination node that receives a packet has to know what 
to do with it. Since one node might have several different usages 
for packets, another protocol layer ‘on top of’ the ALAP can 
distribute packets received in one node to different processes, 
called sockets. The protocol that ensures that a packet arrives at 
the right socket is called the Datagram Delivery Protocol (DDP). 

DDP does the following: When a packet is received on a 
node, its data contains a socket number in the header. The 
Appletalk driver that handles DDP maintains a socket table 
which it searches for a match. If no match is found, the packet is 
simply ignored. If there is a match, control is passed to a listener 
routine which processes the rest of the data packet. This listener 
routine must conform to certain timing restrictions since the data 
keeps coming in at a rapid rate. Inside Mac Vol.II explains in 
detail how to write a listener routine. 

DDP also handles the transfer of packets that are sent to other 
networks. As you probably know, several Appletalk networks 
may be interconnected by bridges to form a large internet. The 
internet might even include networks like Ethernet which use 
completely different data transfer mechanisms on the hardware 
and low-level software levels. 

DDP can send a packet to an internet address. Such an 
address contains the network number, node ID and socket 
number of the destination. If the network number is the network 
that the node is on, the packet is simply sent to that node. If the 
node sits on another network, DDP sends the packet to a bridge 
on its own network (if there is one). The bridge then will know 
how to forward the packet. This ‘routing’ process and the way the 
bridges get to know about all the other networks on the internet 
is explained in great detail in Inside Appletalk. All we need to 
know here is that if you call DDP with an internet address that 
corresponds to an existing node and socket on some network, 
your data will (hopefully...) get there. 


NBP 
How does one find out whether a certain node exists on a 
large internet? Numbers are hard to remember, and they also can 
change since node IDs are always assigned dynamically, and 
socket numbers may be. Therefore there exists a mechanism - the 
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name binding protocol (NBP) - to assign unique names to 
sockets at a node. 

Any device on the network can be assigned a name. For 
instance, the Laserwriter called ‘Laser#1’ on the third floor could 
be called 


“Laser#1:LaserWriter@3rd_floor” 


where the first part of the name, up to the colon, is the actual 
device name, the second part, up to the ‘@’, its type, and the final 
part the zone where the device is located. 

Each network has a zone name assigned. Several networks 
can have the same zone name, but one network can have only one 
zone name. Looking for all Laserwriters in a particular zone will 
give the network addresses of all Laserwriters on all networks 
included in that zone. Bridges know about zones and the net- 
works they include; Again you don’t need to be concerned with 
the details how this is achieved. For the curious, this is well 
explained in Inside Appletalk’s sections on the Routing Table 
Maintenance Protocol (RTMP) and the Zone Information Proto- 
col (ZIP). 

For the less curious it is sufficient to know that there exist 
Appletalk driver calls which will for instance, given a name like 
“Laser#1:LaserWriter@3rd_floor” return that printer’s network 
ID, node ID and socket number, or for “=:LaserWriter@ *" return 
a list of addresses of all Laserwriters іп one's own zone (“-” for 
the device name or type acts as a wildcard; “*” indicates the zone 
of one's own network). 


ATP 

OK. So now we can, given the name of some device on the 
network, find out its address. What do we do with it? 

Usually we will send some data to that device, and maybe 
receive some other data in return. Using DDP, this could for 
instance be done in the following way: 

- create a socket on the node and associate to it a listener 
routine that will store the data received on that socket; 

- send a data packet to the other device, using its network 
address that has been looked up using NBP. DDP will add 
addressing information to the data so that the receiving end 
knows where to send its response to. 

.- when a response is received from the other device, the 
listenerroutine willstore the data and notify the program that data 
has arrived. 

Note, however, that on a big internet packets might get lost, 
maybe some bridge breaks down or a whole network is discon- 
nected. This might not be known to the sender at send time. 
Therefore, the algorithm that I just described will not necessarily 
ensure that the data arrives at the remote device. We would need 
to implement some acknowledge mechanism which re-sends a 
packet a certain number of times if its reception is not confirmed 
by the remote device after some timeout period. 

Fortunately we don't have to implement such a mechanism, 
as it has been provided for us in the Appletalk Transaction 
Protocol (ATP) driver. The two partners in a data transmission 
- therequesting and the responding end - are called the client and 
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the server and interact in the following way: 

- А server opens a responding socket on the network using 
the routine ATPOpenSocket. ATP automatically assigns a lis- 
tener routine to that socket that will dump the received data into 
a previously assigned buffer. 

- The server will then call the routine ATPGetRequest. This 
routine will return (or, for asynchronous calls, the IOCompletion 
routine will be called) when a request data packet has been 
received. 

- Weassume that the client knows the network address of the 
server. Otherwise, the server would have to register its name on 
the network and the client could find the address through that 
name. 

- Theclientcalls ATPSendRequest with the network address 
of the server, and up to 578 bytes of request data in a buffer. This 
data will be transmitted to the server; ATP makes sure it gets 
there. ATPSendRequest waits for a response from the server, 
which can contain up to eight data packets; it will retransmit the 
request as long as not all data packets have been received. For the 
duration of the transmission and for receiving the response, 
ATPSendRequest opens a socket and automatically closes it 
when itreturns. You, the programmer, normally don'tnotice this. 

- The serverreceives the request data packet and puts it away 
into a buffer; ATPGetRequest returns and the server calls 
ATPSndRsp which transmits the response, up to eight buffers of 
data of amaximum of 578 bytes each. The response also contains 
information how many buffers in total will be sent (1 to 8), and 
which one is being sent in each particular packet. The client end 
(ATPSendRequest) maintains atable to know which packets have 
been received. АП this is handled automatically by ATP. 

There are even higher-level protocols (Printer Access Proto- 
col, Appletalk Session Protocol, Appletalk Filing Protocol) 
which use ATP to implement particular functions. They don't 
concern us here, but are described in Inside Appletalk and the 
Appletalk chapter of IM Vol.5. We have all the necessary 
information to implement the example program, a very basic 
mail utility. 


Appletalk mail example 

Our example consists of two programs (stand-alone on the 
source code disk): the sender and the receiver. The receiver will 
be known on the network as «choosername»:mailbox(2 «zone» 
where <choosername> is the user name given in the Chooser 
dialog and «zone» the zone where the network is located. 

The receiver task operates in the following way: First, it 
opens ап ATP responding socket by calling ATPOpenSocket. 
Then, using its socket number, it makes itself known to the 
network with a registerName call to the NBP. Last, it calls 
ATPGetRequest asynchronously and puts itself to sleep (storing 
SLEEPin its STATUS address and calling PAUSE); the IJOCom- 
pletion routine will wake it up again when the request hasarrived. 
The request contains the mail message, which is displayed. Then, 
the receiver task sends a response, which consists of one buffer 
of data with no particular information in it. At the end, the task 
closes the socket and removes its name from the network. This 
cycle is repeated until a key is pressed. 
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The sender task will first search the network for any devices 
that match the name description “=:mailbox@*” (i.e., all open 
mailboxes in its own zone). It will display the list of mailboxes 
with their network addresses. Then it prompts for the address 
where the message should be sent, and for one line of message 
text. It calls ATPSendRequest with the mail message in the 
request data block. When it has received the response from the 
receiver (or has received no response, in which case it generates 
atimeouterror), it starts the cycle again, searching for mailboxes. 

I should apologize here for the very experimental implem- 
entation of this ‘message service’. There are absolutely NO 
errors trapped, and the example will work only if you start the 
receiver on one Mac, then start the sender on another Mac, and 
then start sending mail. It will also not (yet) run in background 
under Multifinder; and the interface is certainly far from the User 
Interface Guidelines. However, the example can give youa basis 
on which to start your own experimentation. 


Mach2 Appletalk words 

After these general remarks, let’s look at the Forth code. The 
constant definitions are taken from Inside Macintosh and from 
the Atalk.h header file in Bob Denny’s Appletalk example from 
У2#10. All Appletalk routines are accessed through calls to 
either of two. drivers: MPP, which implements ALAP, DDP, 
RTMP and NBP, and .ATP, which implements ATP. Their driver 
IDs are 9 for .MPP and 10 for .ATP. 

At the beginning of a program that uses Appletalk you 
should check whether port B is configured for Appletalk use; if 
the low four bits of system global SPConfig ($1FB) contain 1, 
this is the case. (See IM П-305). OpenATalk checks the ports and 
opens .MPP and .ATP if necessary. 

АП Appletalk driver calls are passed through a parameter 
block, ATPblock. I am always using the same global block, thus 
we can make at most one asynchronous call at a time. For this 
simple example this is sufficient. The words I wrote to call the 
different Appletalk functions that we need here all set up the 
parameter block first, then issue the driver Controlcall through 
call.atp or call.mpp. I have deliberately not used assembler to set 
up the parameter block, but you might recode the glue in 
assembler to save code space. 

For further details on the Appletalk calls you should refer to 
IM Vol П. For the ATPGetRequest function, we implement an 
asynchronous call to the .ATP driver. The word call.atp.async 
implements this function. In fact, all I/O calls that take more than 
a few milliseconds should be handled this way, especially in a 
multitasking environment like Mach2. However, for ATPGetRe- 
quest it is more essential than for the other functions, since that 
call never times out and thus would hang forever if the request is 
not satisfied. 

For an asynchronous I/O call in Mach2, we define a ‘зета- 
рһоге” variable that will hold the status address of the task issuing 
thecall. This variable iscalled ATPout (Icouldn'tthink of a better 
name). (get.request.async) does a ATPout get first (ATPOut 
must be zero for the task to continue, then the task will put its 
status address into that variable), then the parameter block is set 
up and the asynchronous call made. After the call, the task puts 
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the value SLEEP into its status address and calls PAUSE. This 
will put the task to sleep until the status value is changed back to 
WAKE again. The completion routine does exactly this. Thus 
execution of the task calling (get.request.async) will continue 
after the PAUSE when the completion routine is called. If the 
completion routine is never called (i.e. the task hangs), we can 
always stop the Mach2 system completely by typing BYE in the 
main window. 

Some remarks on name registration: First, if you ever were 
curious where a program gets the Chooser user name from, it is 
contained in 'STR * resource -16096 (local resource ID=0 of 
DR VR ID=9). get.choosername gets this name for you. 

The calls to register.name and lookup.name are made syn- 
chronously, and they take several seconds. If that seems too long 
to you, you can replace those by asynchronous calls as well, but 
make sure to use different parameter blocks for each call to avoid 
big trouble. The name of a network device is contained in a 
special data structure called a names table entry or NTE, whose 
format is given in IM II-321 (Fig. 13). The word make.entity is 
used to construct the ‘entity name’ field of the NTE. When 
searching for network names with lookup.name, the list of names 
returned is in the format of several such entities. The words 
next field and print.entities (further down in the listing) are used 
to traverse this list and print the names with their addresses in a 
readable format. Since the four-byte network address in that table 
may start at an odd byte, I also had to define >@<, which does 
a long word fetch at an odd address (I discovered this when I 
checked the example on a Мас+ and got an address error! There's 
adisadvantage using the MacII, you don'tdiscover such things!). 

Finally, while the data from an ATP request is simply put 
into a buffer, the data for the response must be contained in up to 
8 separate buffers. Whatis actually passed to the (send.response) 
routine is the address of a buffer descriptor structure (BDS) 
containing 1 to 8 entries of 12 bytes each. The addresses of the 
different buffers and the length of the data are contained here (see 
IM П-288). The words setup.bds and release.bds are provided to 
get and release heap space for the ATP buffers. 

Well, I'll let you look at the code for the rest of the 
implementation and finish with some news from my side of the 
Atlantic that might be interesting to Mac people on both sides. 


International shareware payment 
- a Solidarsoft initiative - 

А great problem for European users with using shareware 
products written in the US has always been the transfer of money 
across the Atlantic. Mailing checks is possible in principle, but 
usually the only onesthat geta profit out of thatare the banks with 
the high fees they charge for cashing foreign checks. Buying 
international money orders also can get expensive, and sending 
cash might or might not work. The second problem arises when 
shareware programs are used within a company or organization 
that needs a receipt for tax or other purposes. 

It seems to be so difficult to pay shareware from overseas 
that the author of McSink has kindly offered his program to 
overseas users because his bank charges him more for cashing the 
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check than his profit would be after taking away the cost of \ М5. Я 
shipping an update disk overseas! Е 2 constant LAPLongDDP 
Solidarsoft, the French non-profit organization that was | -94 constent 1арРгоїЕгг 
founded to help improve software developer/publisher/userrela- | -95 constent lapExcessCol Ins 
tionships and that I already told you about, has nowcomeup with | 243 constant lepiirite 
a scheme that greatly facilitates international shareware pay- | 244 constent lepDetachPH 
ment. You send a check to Solidarsoft with a letter giving the | 245 constent lepAttachPH 
name and version of the shareware product and the author's | ., constant lapOverrunErr 
address, or the shareware registration form, and they will handle | -2 constant lapCRCErr 
therest: make sure that the author gets the correct $$$ amount (by Br sed т. араса 
some economic way of money transfer), and that you will be Cona tans. Таро ere 
correctly registered with the author. Using this service will be | \ 00Р defs 
only slightly more expensive for a French shareware user than | 9 constant ddpHdSzShort 
А : А 13 constant ddpHdSzLong 
going to the bank, getting the paperwork done, and paying the 
author directly. Currently, to cover banking fees and othercosts, | 1 constant ddpRTMP 
Solidarsoft is applying the following formula: : constant Се 
Youcount the US$ at 6.50 French francs (FF). On top of that, Сре 
you add 43 FF handling charge for international payments and 5 | $7F constent ddpMexWKS 
FF for payments within France. If a check does not cover the n iod E 
А А ° en 
shareware fees plus handling, e.g. in the case of changing 128 constant ФИК, 
exchange rates (the dollar is going up as of this writing), it will 
simply be returned with an explanatory note. So to pay a $25 | -91 constent ddpSktErr 


shareware product, you send the registration form together with E Maio Weis RUE 


a check on 205.50 FF to: 
N CsCode values Гог DDP Control calls- MPP 
. 246 constant ddpWrite 
Solidarsoft, | 247 constent ddpCloseSkt 
66 boulevard Exelmans, F-75016 Paris, France. 248 constant ddpOpenSkt 


N RTMP definitions 


Let’s hope this example catches on elsewhere. Till next 1 constant rtmpSkt 


month, happy threading. 

\ NBP definitions 
Listing 1: Appletalk handling from Mach2 $10 constant nbpBrRq 

$20 constant nbpLkUp 
N Appletalk general definitions $30 constant nbpLkUpReply 
\ 30.05.88 JL 2 constant nbpSkt 

15 constant nbpTupleMax 
only forth also assembler ascii = constant nbpEquals 


ascii * constant nbpSter 
vocabulary network 


also network definitions € constant ntLink 
4 constent ntTuple 
DECIMAL 71 constant ntSocket 
9 constent ntEntity 
27 constant ioPermission 
18 constant ioF i leName - 1024 constant nbpBuf fOvr 
18 constant userData -1825 constant nbpNoConf irm 
24 constant ioRefNum -1026 | constent nbpConfDiff 
26 constant csCode -1027 constant nbpDuplicate 
28 constent socket -1028 constant nbpNotFound 
38 constant eddrBlock - 1029 constant nbpNISErr 
4 constant atpLoadedBit | 249 constant nbpLoad 
1 constant useATalk 250 constent nbpConf irm 
-97 constant portInUse 251 constant nbpLookup 
-98 constent portNotCf 252 constent nbpRemove 
| 253 constent nbpRegister 
9 constent mppUnitNum 254 constent nbpKill 


255 constent nbpUnload 


10 constent atpUnitNum 256 constant setSelfSend 


mppUnitNum 1+ negate 


constant mppRefNum \ ATP definitions 
atpUnitNum 1+ negate $40 constant atpReqCode 
constant atpRefNum $80 constant atpRspCode 


$C constant atpRelCode 
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$20 constant atpXO 

$10 constent atpEOM 

$08 constant atpSTS 

$02 constant etpTidValid 
$21 constant atpSendChk 

$3F constant atpF lagMask 
$F8 constant atpControlMask 


8 constant atpMaxNum 
578 constant atpMaxData 


249 constant atpRelRspCB 

258 constant atpCloseSkt 

251 constant atpAddResponse 
252 constant atpSendResponse 
253 constant atpGetRequest 
254 constent atpOpenSkt 

255 constant atpSendRequest 
256 constant atpRelTCB 


- 1096 
- 1097 
- 1098 
- 1099 
- 1100 
-1101 
- 1102 
-1103 
-1104 
-1105 


constant atpReqFailed 

constant atpTooMangReqs 
constant atpTooManySkts 
constant atpBadATPSkt 

constant atpBadBuf f Num 
constant atpNoRelErr 

constent atpCBNotFound 
constent atpNoSendResp 
constent atpNoDataArea 
constant atpReaAbor ted 


$ IFA constant pRamByte 
$1FB constant SPConf ig 
$291 constant por tBUse 
$208 constant ABusVars 
%20С constant ABusDCE 


9 constant bdsBuffSz 
2 constant bdsBuf f Addr 
6 constant bdsDataSz 
8 constant bdsUserData 


. trap 


-control,async $а404 


header ATPbuffer 2000 allot 
header myBDS 8 12 * allot 
header reqBuf 600 allot 
header. myNTE 100 allot 
header ATPblock 50 allot 


header MPPName 


DC.B 
DC.B 


4 
«MPP? 


header ATPName 
06.84 


DC.B 


* ATP?’ 


: Open.atp 
PortBUse ce $10 and 


IF 0 
ELSE 


THEN 


\ Appletalk already open! 


[°] ATPName ['] ATPBlock ioFileNeme + ! 
0 (71 ATPBlock ioPermission * c! 
[^] ATPBlock call Open 


: ореп.трр 


[°] MPPName ('] ATPBlock ioFileName + ! 
Ø [°] ATPBlock ioPermission + c! 
[°] ATPBlock call Open 
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: OpenATalk ( | PBUse - f ) 
PortBUse сё -> PBUse 


PBUse 2‹ 
IF SPConf ig ce $F AND 2 = 
IF portNotCf 
ELSE 
open.mpp ?dup 0- 
IF open.atp THEN 
HEN 


ELSE 
PBUse $F and 1- 
IF open.atp 
ELSE portInUse 
THEN 

THEN 


: close.atp 
ATPRefNum [^] ATPBlock ioRefNum * w! 
[^] ATPBlock cal! Close 


: call.npp 
nppRef Num (71 ATPBlock ioRefNum + w! 
[^] ATPBlock call control 


: call.atp 
etpRef Num (”1 ATPBlock ioRefNum + w! 
[°] ATPBlock call control 


: call.etp.async ( p_complete - flag ) 
atpRef Num (^] ATPBlock ioRefNum + w! 
С p-complete) ('] ATPBlock ioCompletion + ! 
LEA ATPBlock, Аб 
EXG D4,A7 
-Control , Async 
EXT.L 00 
MOVE.L 00,-(Аб) 
EXG 04, АТ 


: open.socket С addrBlock socket! - socket! flag ) 
С socket? ) [’] ATPBlock socket + c! 
€ addrBlock 2171 ATPBlock addrBlock + ! 


&tpOpenSkt (71 ATPBlock csCode + w! 
call.atp 

(71 ATPBlock socket + ce 

swap 


: close.socket С socket# — flag ) 
С socket? ) |71 ATPBlock socket + c! 
etpCloseSkt 171 ATPBlock csCode + w! 
cell.atp 


, 


: (send.request) С userData atpFlags addrBlock 
reqLength reqPointer 
bdsPointer numOfBuffs 
timeQutVal retryCount - 
reqTID BitMap atpFlags numOfResps flag ) 
С retryCount ) Г”) ATPBlock 47 + c! 
C timeQutVal ) [°] ATPBlock 45 + c! 
C numOfBuffs ) [°] ATPBlock 44 + c! 
C bdsPointer 2 [°] ATPBlock 40 + ! 
С reqPointer ) [*'] ATPBlock 36 + ! 
С reqLength 2171 ATPBlock 34 * w! 
С addrBlock 2171 ATPBlock 30 + ! 
С atpFlags ) Г] ATPBlock 29 + c! 
С userData ) [“] ATPBlock 18 + ! 
atpSendRequest [^] ATPBlock csCode + w! 


$13 


: Cget.request) 


. 
д 


са11.аїр 

(71 ATPBlock 16 + we 
(^) ATPBlock 28 + сё 
(71 ATPBlock 29 + сё 
(41 ATPBlock 46 + сё 

4 roll С result code ) 


С atpSocket reqLength reqPointer - 
userData atpFlags addrBlock reqLength 
bitMap transID flag ) 

( regPointer ) (71 ATPBlock 36 + ! 

( reqLength 2171 ATPBlock 34 + w! 

С atpSocket 2171 ATPBlock 28 + c! 

call.atp 

(^] ATPBlock 18 + e 

[^] ATPBlock 29 + сё 

(71 ATPBlock 30 + e 

(71 ATPBlock 34 + we 

(71 ATPBlock 44 + сё 

[°] ATPBlock 46 + сё 

6 roll € result code ) 


variable ATPout С semaphore ) 


code get.request.comp] 


movem.] 
movea.1 
movea. | 
move .W 
movem. 1 
rts 


80/85, -CaT) 
currentad, ad 
ATPout, а0 
"wake, (að) 
(872*,80/85 


end-code 


(get.request.async) ( atpSocket reqLength reqPointer - 
userData atpFlags eddrBlock reqLength 
bitMap transID flag ) 

ATPout get 


C reqPointer ) (^) ATPBlock 36 + ! 
( reqLength 2171 ATPBlock 34 + w! 
С etpSocket 2171 ATPBlock 28 + c! 
[^] get.request.comp) call.atp.async 
Sleep status и! pause 

V wake up when getRequest is completed 
(71 ATPBlock 18 + @ 
(41 ATPBlock 29 + сё 
(71 ATPBlock 30 + e 
(71 ATPBlock 34 + wé 
(71 ATPBlock 44 + с@ 
[°] ATPBlock 46 + сё 
6 roll ( result code ) 
ATPout release 


: setup.bds С "buffers ) 


0 DO 
609 call NewPtr abort? Could not get buffer memory" 
i 12 ж (71 myBDS + 2+ ! 

LOOP 


: release.bds ( "buffers ) 


0 00 

i 12 * ['] myBDS + 2+ @ 

call DisposPtr abort” DisposPtr failed!” 
LOOP 


‚ (send.response) ( atpSocket atpFlags addrBlock 


bdsPointer numOfBuffs bdsSize trensID - 
reqTID userData flag ) 


С trensID ) [°] ATPBlock 46 + и! 
( bdsSize ) [°] ATPBlock 45 + c! 
514 


д 


С numOfBuffs ) (71 ATPBlock 44 + c! 

( bdsPointer 2 [^) ATPBlock 40 * ! 

С addrBlock 2171 ATPBlock 30 + ! 

( atpFlags ) 171 ATPBlock 29 + c! 

( atpSocket 2171 ATPBlock 28 + c! 
atpSendResponse  ('] ATPBlock csCode + w! 
call.atp 

[^] ATPBlock 16 + we 

[^] ATPBlock 18 * e 

rot € result code ) 


: Cadd.response) 


) 


( userData atpSocket atpFlags addrBlock 
reqLength reqPointer rspNum transID - 
flag ) 

[^] ATPBlock 46 * w! 

rspNum ) (71 ATPBlock 44 + c! 

regPointer ) (71 ATPBlock 36 * ! 

reqLength 2171 ATPBlock 34 + w! 

addrBlock 2171 ATPBlock 30 + ! 

atpFlags ) 1”) ATPBlock 29 + c! 

atpSocket 2171 ATPBlock 28 * c! 

userData 2 (')] ATPBlock 18 + ! 

atpAddResponse [°] ATPBlock csCode + w! 

call.atp С result code ) 


trensID 2 


` ` о лына 978 í" Pg 


: load.nbp 


nbpLoad [^] ATPBlock csCode + w! 
call.mpp 


: make.entity ( object typ zone entity | obL typl - ) 


object entity over с@ 1+ dup -? obL cmove 
typ X entity обі + over сё 1+ dup -> typL 
zone entity обі + typL + over сё 1+ 


стоуе 
стоуе 


: Clookup.name) С interval retry buffer size max entity – 


matches flag ) 


nbpLookup (^] ATPBlock csCode + w! 
С entity ) |171 ATPBlock 30 + ! 

( mex ) (^) ATPBlock 40 + w! 

( size ) ['] ATPBlock 38 + w! 

( buffer ) ГС“) ATPBlock 34 + ! 

( retry ) [°] ATPBlock 29 + c! 

СГ interval) 171 ATPBlock 28 + c! 


call.mpp 
[^] ATPBlock 42 + w@ X matches found 
swap \ result code 


: lookup.name ( object typ zone | - matches flag ) 


(^] nyNTE ntEntity + make.entity 
2 10 171 ATPbuffer 600 20 ['] myNTE ntEntity + 
Clookup.name) 


: (register.name) С interval retry ntQEl verify - flag ) 


nbpRegister І”1 ATPBlock csCode + w! 
( verify ) ['] ATPBlock 34 + c! 

( ntQEl ) (71 ATPBlock 30 * ! 

С retry ) (41 ATPBlock 29 + c! 


( interval) ГС“) ATPBlock 28 + c! 
call.mpp N result code 


: register.name ( socket? object typ zone ) ( ntQE1 | - flag ) 


ПІСЕТ ntEntity + meke.Entity 
ntQE1 ntSocket + c! С store socket number ) 
2 10 ntQE] 1 C always verify ) (register .name) 
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: remove.name C һі0Е1 | flag 2 
nbpRemove [^] ATPBlock csCode + w! 
C ntQE] ) ntEntity + Г] ATPBlock 30 + ! 
call.mpp X result code 


: set.self.send ( self send. flag | old. flag - ) 
setSelfSend ['] ATPBlock csCode + w! 
C flag ) [^] ATPBlock 28 + c! 
call.mpp drop \ result code 
[^] ATPBlock 29 + ce 


д 


4ascii STR constant "str 
4ascii MAIL constant “mail 


: get.choosername 
“str – 16096 call getresource 
?dup IF 6 ELSE 1 abort’ No Chooser name found!” THEN 


also forth definitions 


variable mailbox.socket 
header mailNTE 110 allot 


: open.mailbox 
0 В open.socket abort? could not get free ATP socket” 
dup mailbox.socket ! 
get.choosername ^ mailbox” ” *^ [°] mailNTE 
register.name abort? registerName failed” 


: close.mailbox 
[°] mailNTE remove.name drop 
mailbox.socket 6 close.socket drop 


: sendOK 
cr .^ — Sending ОК response..... i 
1 setup.bds 


* This mail was received OK.” count dup [°] myBDS w! 
[^] myBDS 2% 6 swap cmove 
[°] myBDS (71 ATPBlock 40 + ! 
1 ГЈ ATPBlock 44 + c! 
1 (71 ATPBlock 45 + c! 
atpSendResponse  ['] ATPBlock csCode + w! 
call.etp 
1 release.bds 


) 


: get.mail ( | trID addr.block - reqTID userData flag } 
mailbox.socket @ 500 ['] reqBuf Cget.request) 
abort^ ATPGetRequest еггог!” 

5 call sysbeep 

-> trID drop С don’t need bitmap ) 

cr .^ ***** Mai] received *****4 

cr [°] reqBuf swap type 
cr .^ ***** End of mail 
dup -> addr.block 

cr .^ sender: $^ hex . 


ЖЖЖЖЖ^ 


.”, flags: $”. ." , User Data: $^ 


cr decimal 
send0K 


2 


: get.mail.async ( | trID addr.block - reqTID userData flag } 
mailbox.socket @ 500 (71 reqBuf (get.request.async) 
abort” ATPGetRequest error!” 

5 call sysbeep 
-› trID drop С don’t need bitmap ) 
cr .” ***** Mail received ****s^ 


© The Definitive MacTutor, Vol. 4 


cr [°] reqBuf swap type 
cr .^ ***** End of mail 
dup -> addr .block 

cr ." sender: $^ hex . 


хххжж” 


." , flags: $^ . ." , User Data: $^ 


cr decimal 
sendOK 


: ›6‹ € odd address fetch, unnecessary on MacII ) 
dup 2 mod 
IF dup с@ swep 1% 6 -8 scale $FFFFFF and swap 24 scale + 
ELSE e 
THEN 


: next.field dup сё + 1+; 


: print.entities С entities entityTable ) 

cr Swap hex 

‚000 .? $” dup @c u. .^ - * 
5 + dup count type .” :” 
next.field dup count type .^ 0” 
next.field dup count type cr 
next.field 

LOOP drop 

decimal 


д 


: find.boxes 
* =” © mailbox” * *^ lookup.name 
abort” LookupName failed” 
cr ?dup IF dup . .^ mailboxCes) found on the network:^ cr 
(71 ATPBuffer print.entities 
ELSE .^ No mailboxes found on the network.” cr 
THEN 


: send.mail ( receiver msg | - } 
cr ." Sending message to $^ 
receiver hex . decimal .^ ...” cr 
1 setup.bds 
"mail %00 100000 receiver 
msg count swap ['] myBDS 1 2 5 
(send.request) 
?dup IF .* SendRequest error 8” . cr 
ELSE .^ Mail delivered" cr 
THEN 
CREE. 
1 release .bds 


also mac 


NEW.WINDOW Sender 

* Sender^ Sender TITLE 

40 20 170 400 Sender BOUNDS 

Document Visible CloseBox GrowBox Sender ITEMS 


400 1000 TERMINAL sendTesk 


NEW.WINDOW Receiver 

* Mailbox^ Receiver TITLE 

190 20 320 400 Receiver BOUNDS 

Document Visible CloseBox GrowBox Receiver ITEMS 


400 1000 TERMINAL rcvTask 
: mail.it 
activate 


begin 
cr .^ Searching open mailboxes...” cr 
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f ind.boxes 


hex 
begin : Setup.main 
cr .” To address (zero to quit): $^ 0 ATPout ! 
ped dup 1% 10 expect number? open.mpp drop 
until ореп.аїр drop 
1 set.self.send drop 
?dup IF ; 
cr .” Message: “ 
ped 1* 89 expect : Setup.sender 
span pad c! setup.main 
pad send.mail Sender ADD 
ELSE bye Sender sendTask BUILD 
THEN Sender call selectwindow 
again sendTesk mail.it 
; ; 
: get. it : Setup.rcv 
activate setup.main 
begin Receiver ADD 
cr .” Registering new Mailbox...” Receiver гсуТазк BUILD 
Open .mai 1box Receiver call selectwindow 
cr .^ Waiting for mail...” cr rcvTesk get.it 


get.mail.async drop 
close.mailbox 
terminal until 
bye 
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Forth Forum 


Jórg Langowski 
MacTutor Editorial Staff 


The Notification Mana ger MACH 2 МасТшог Vol. 4 No. 10 
Notification Manager, List Manager and Userltems | program, 


System updates are almost too frequent to keep track of. It 
has been only a couple of months since I installed release 6.0; 
already there are a couple of bug fixes out. I couldn't get them as 
of this writing, but System 6.0 has behaved stable so far, ex- 
amples of ill-behaved applications are only very rare. 

The scene keeps moving. As I write this, System 6.0.1 is 
almost released and 7.0 is being talked about; true to the old 
wisdom “if one version of the operating system finally behaves, 
go install a new one". Anyway, the example I am giving today 
explores a new service added in System 6.0 under MultiFinder; 
the notification manager. 

This is one of the little things - one might say - added on the 
way to ‘Real Inter-Process Communication’, and it isresponsible 
for the little printer icon you see flashing with the Apple symbol 
in the menu bar when your background printer has a problem, or 
the clock icon when your alarm clock goes off. 

Actually, this month's program deals with many different 
things, the notification manager being only one of them. I wanted 
to create some useful utility that can keep track of appointments 
and remind me if something's coming up, just like the Reminder 
DA in one of my recent columns. However, this time I wanted to 
be able to enter date and time in a well-readable format, and also 
keep a file with the appointments that is automatically read in on 
startup and updated on exit. It turned out that doing these things 
inanice way required some use of the list manager and a user item 
ina modeless dialog; so the example will show you some of those 
things as well. 


The Plan 

The program consists of a modeless dialog window which 
displays a list of appointments with their dates and corresponding 
messages. Selection, updating and scrolling of the list is handled 
by the list manager. The dialog allows the user to edit a list item, 
add and delete appointments, and exit the program. 

As long as the dialog window is up, a background task 
(easily created under Mach2) keeps doing the following things: 

- Each time the list is changed (by adding/editing/ deleting 
things), it gets the time and message of the next upcoming 
appointment from the list. 

- When the system time exceeds the time of the upcoming 
appointment, a Notification Manager (NM) request is set up. The 
NM then displays an alert message with the appointment mes- 
sage. After the message, the program gets the next appointment 
from the list. 

- When the main dialog window is closed, the background 
task writes the appointment list back to the file and terminates the 
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88/08/18 09:30:00 Guten Morgen! 
88/08/19 10:30:00 Applelink MacTutor Art 
88/08/19 12:00:00 Lunch Break! 


Figure 1. Main dialog window of this month’s 
example 


implementation 

First of all, we need to create a modeless dialog window that 
contains a list. Since that is not a standard dialog item, it has to 
be implemented as a user item. Just as a reminder: a user item is 
anything in a dialog that has to be drawn using our own procedure 
when the dialog is updated. A pointer to the drawing procedure 
is passed to the dialog manager by calling SetDItem, as described 
in TN34: 


First call: 

GetDItem (DialogPtr, itemNo, type, item, box); 

check if necessary whether type is really the type of a 
userItem, and then call 


SetDItem (DialogPtr, itemNo, type, @drawProc, box); 
where @drawProc is a pointer to the user-supplied draw 


procedure. Note that it is really a pointer that is passed here, not 
a handle like in the case of other dialog items. DialogPtr, of 
course, is the pointer to the dialog window, where the item 
itemNo has been defined as a изегИет, and box is the rectangle 
where the item will be drawn. 

We сап install a user item procedure from Масһ2, but, if we 
just passed any Mach2 routine's pointer to the SetDItem trap, the 
machine would crash gloriously when trying to draw the item, 
because the procedure is not called from the Mach? context, but 
through the dialog manager. This means, glue code has to be 
written-something you should be used to by now. 
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Іп the example, the routine gUser provides this service, 
setting up space on the stack for the local Forth and DO...LOOP 
stacks, saving all the registers, and moving the dialog pointer and 
item numbers on the Forth stack. It then calls the UserDraw 
procedure and cleans up after it has returned. 


List Manager 

Our user item will contain a list. How do we handle it? IM 
VoLIV describes the List Manager routines, and using those the 
job becomes pretty easy. I am not going to review the List 
Manager in detail; IM gives a pretty good description, and we 
also had an article last year describing the list manager (V 3414). 

For the drawing procedure, all we need is a call to LUpdate, 
which redraws the list. This is implemented in UserDraw (see 
Listing). However, here we assume the list has already been 
setup. This is done at the start of the program, calling installUs- 
erDraw which calls MakeList. The latter routine (taken from Palo 
Alto Shipping's ListManager example) creates a list in a given 
rectangle and window with vertical and horizontal cell size given 
in pixels. Looking at the example you will also notice that our list 
has a vertical scroll bar; the list manager handles scrolling 
automatically. Note that the list rectangle was inset by one pixel 
with respect to the user item rectangle, except for the right side 
where the scroll bar appears, where it had to be inset by 16 pixels 
(the scroll bar is drawn outside the list). After the list is created, 
its handle is stored in a variable for further use. 

We now need a handler for mouse down events in the user 
item; and also routines that will allow us to edit, add and delete 
list items when the appropriate buttons in the modeless dialog are 
pushed. The words userList-handler, userEdit, userAdd, and 
userDelete are provided for this purpose. 

Mouse down events in the user item are handled by userList- 
handler. It calls LClick with the local mouse position, the modi- 
fiers word of the event record and the list handle. (Note that 
event-record is a Mach2 system variable which points to the 
latest event record). LClick handles selection of list elements, 
highlighting, scrolling, and double clicks. If a list item is double- 
clicked, the userEdit procedure is called; otherwise, the routine 
just returns, with the list selection changed. 

userEdit and userAdd set up a modal dialog which allow a 
date and text to be entered into a message field. While userAdd 
adds a new field at the end of the list, userEdit takes the current 
selection, puts the date and message into the modal dialog, and 
lets the user edit it. getMsg is the routine that parses the message 
string into its date and message fields and displays the edit dialog. 
update-cell writes the current date/message string into the se- 
lected cell. userDelete simply deletes the currently selected cell. 

Anumber of thingscould be improved here: mainly, I did not 
implement automatic sorting by date when a list item is added or 
edited. This is straightforward and would require one or two more 
pages of code; since itis notreally essential for the operation, I'm 
leaving it as an exercise for you. 

The list is initially filled from a file called ‘dates’ which has 
to be in the same folder as the application. If it doesn't exists, it 
will be created. dates contains the date/message strings, sepa- 
rated by carriage returns, and can be edited like any text file. fill- 
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list opens - or creates - the file, reads the strings and adds rows to 
the list. At the end of the program, write-list writes the list back 
to the file. This way, by making the program one of your 
Multifinder startup applications, you will be automatically 
reminded of any upcoming appointment that was entered into the 
list. 


Modeless Dialog Handling in Mach2 

What has to be done to handle modeless dialogs correctly in 
a multitasking environment like Mach2? Since events аге 
handled for us by the I-O task, we need not - and should not - call 
WaitNextEvent, IsDialogEvent, or DialogSelect from our pro- 
gram. This has already been done for us. All we need to do to 
connect a modeless dialog window with one particular task is 
install the task pointer in the dialog window's refCon field. The 
I-O task will look at the front window's refCon and pass the event 
information to the owning task. In the case of a dialog event it will 
put the dialog pointer and the item number into the user variables 
DialogHandle and DialogData (offsets 140 and 136). When data 
is stored there, the owning task will run the modeless dialog 
handling routine whose pointer is stored in the user variable 
modelessVector (offset 132). This routine gets passed the item 
number and the dialog pointer. Our program uses the word 
dialog-handlerto call the handlers for the individual dialog items. 
The pointer to this routine is installed on starting up the task; 
likewise we install a pointer to a menu handling routine, which 
allows to handle desk accessories, a simple file menu which can 
only quit the program, and an Edit menu which allows for editing 
in desk accessories (in case you ever want to run this program 
from the finder, which is not very likely). Setting up the menus 
and menu handlers should be self-explanatory from the listing. 


The Main Program 
The main program window is hidden behind the menu bar, 
its coordinates being (1,1,16,16). This is because Mach2 canonly 
assign a menu bar to a terminal task, therefore we need a main 
window. I have not tried whether - since we also have the dialog 
window associated with the task - the main window can be simply 
made invisible by calling HideWindow, so I simply used the 
*üny-window-behind-menu-bar' method that one would use in 
Mach2 for having menus without a window. 


The main task loop does two things: 

- checks whether an appointment has ‘matured’ and must be 
displayed using the Notification Manager (check, next date); 

- checks whether the dialog window is still visible. If itis not, 
the user has closed it and the program should write the list back 
to the file and exit (check dialog up). 


A flag, nmChanged, is kept to indicate whether 
check next date should search the list for the next appointment 
due or simply compare the time of the last appointment read with 
the system time. The flag is set by the list editing routines, and by 
check next date itself when it has displayed an appointment. It 
is reset by the routine that gets the next appointment from the list. 
check next datecallssay. it when the system time has exceeded 
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the time of the appointment. say. it (finally!) calls the Notifica- 
tion Manager. 


Notifying the User 

The actual notification routine, as it turns out, is the smallest 
part of the program and of my column. say_it first checks the flag, 
nmPresent, which has been set at startup time to indicate whether 
the NM traps are present. If not, we’re running under an older 
system version, and say_it simply beeps. Otherwise, it calls 
notify-request, our glue routine to the NM/nstall trap. The NM 
traps are explained in TN184, and ГЇЇ repeat some of the 
information here. 

notify-request takes the following parameters from the 
Stack: 

mark, contains 1 if the application should be marked in the 
Apple menu, O if not, or the reference number of a desk accessory 
to mark that desk accessory. 

SIcon, contains a handle (non-purgeable) to a SICN resource 
if a small icon should flash with the Apple icon in the menu bar, 
0 otherwise. 

sound, contains a handle to a sound record to be played with 
SndPlay if a special sound is to be played on the notification; 0 
if no sound should be made and -1 for the system beep. 

str, a pointer to a string to appear in the NM alert box, ог 0 
if no alért. 

resp, a pointer to a response procedure. This is explained in 
more detail in TN184; we simply use -1 to indicate the standard 
system response procedure which simply removes the NM re- 
quest from the queue. If O is passed, no response procedure is 
called, and the program itself would be responsible for removing 
the NM request using NMRemove. 

refCon, a constant available for general use, TN184 suggest 
to store A5 of the calling program here to allow access to the 
application globals. 


myNMRec will contain the NM record in the format given 
in TN184, and NMInstall is called passing its address in А0. 

That's it; the alert will come up when an appointment is due 
if you let the ‘appts’ application (provided on the source code 
disk) turn in the background. Try to experiment with the other 
NM options, the small icons and sounds. 

One last remark: in some cases it might happen that not the 
actual appointment is displayed in the alert box, but the next one 
on the list. This happens when it takes the NM longer than one 
second to get the resources and display the alert. In that case, the 
background task will already have continued and put the next 
message string in the msgTxt global variable! This can be 
remedied by increasing the wait period (presently, 60 ticks) after 
calling say. it in check, next date. 

The necessary resources which have to be added to the 
MACH.RSRC file for running the program are given in Listing 
2, in Rez format. Don't forget to add a SIZE -1 resource as well, 
with the canBackground bit set, and a size of approx. 120K. Good 
luck. 

Mach 2.14 (beta) 
The latest news is a beta version 2.14 of Mach2, which I 
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received recently; as you read this, 2.14 might be released, and 
I'll give you a list of the main changes in one of the next columns. 
Here just a very brief summary: 

- compiler optimization has been improved. 

- local variable handling has been greatly improved, with the 
possibility to reserve blocks of local variable space (i.e. for 
parameter blocks), and customizing the local variable compiler. 

- some words have been added, among them SHIFT which 
takes the function of SCALE that I previously defined. 

- more trap words have been added to the system. The NM 
traps, which I defined here, are included. 

- the disassembler has been enhanced, with listing of refer- 
ences to USER and global variables. 


That's it; till next month. 


Listing 1: Notification Manager example 


V notification manager example System Ver 6.0 needed 
\ JL 15.8.88 


only forth definitions 
also assembler also mac also i/o 
decimal 


N structure of а NM record 


0 CONSTANT qLink N pointer 

4 CONSTANT (Туре — N integer 

6 CONSTANT nmFlags \ integer 

8 CONSTANT nmPrivate N longint 
12CONSTANT nmReserved \ integer 
14 CONSTANT nmMark \ integer 
16CONSTANT nmSIcon N handle 

20 CONSTANT nmSound \ handle 

24 CONSTANT nmStr V StringPtr 
28 CONSTANT nmResp X ProcPtr 

32 CONSTANT nmRefCon \ longint 


8 CONSTANT nmType 


.ТКАР _NMInstall $A05E 
.TRAP _NMRemove $AQ5F 


CODE NMInstall € NMRec - result ) 
MOVE.L (A62*,A0 
-NMInstal] 
MOVE.L 00, -(Аб) 


RTS 
END-CODE MACH 


CODE NMRemove ( NMRec - result ) 
MOVE.L CA6)+, Аб 
_NMRemove 
MOVE .L D@,-CA6) 
RTS 
END-CODE MACH 


$5Е CONSTANT nmTrap® 
$9F CONSTANT unkTrapt 


variable myNMRec 32 vallot 
varieble nmPresent 
\ for checking whether the NM is implemented 
variable nmChanged 
V flag for telling supervisor task 
V that something has changed 
veriable nmSecs 
V time in seconds for next notify alert 
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: notify-request 
( mark SIcon sound str resp refCon | - 
nmPtr result ) 


nmType nynmRec (Туре + w! 
mark  mynmRec nmMark + w! 
SIcon . mynmRec nmSIcon + | 
Sound munmRec nmSound + |! 
str mynmRec nmStr * ! 
resp  mynmRec nmResp * ! 
refCon nynmRec nmRefCon * ! 


mynmRec dup NMInstall 
; 
300 CONSTANT AppleID 


301 CONSTANT FileID 
302 CONSTANT EditID 


2000 CONSTANT updID 
2001 CONSTANT msgID 


110 CONSTANT wVisible \ offset into window record 


132 USER modelessVector 
60 USER fID 


CREATE APPLESTRING $01 C, $14 С, 
NEW. WINDOW nmWindow 


* NM* nmWindow TITLE 
1 1 16 16 nmWindow BOUNDS 
Plain Visible NoCloseBox NoGrowBox nmWindow ITEMS 


600 4000 TERMINAL nmTask 
NEW.MBAR nmBar 


NEW.MENU AppleMenu 

APPLESTRING AppleMenu TITLE 

0 APPLEID AppleMenu BOUNDS 

“ About Appointments ...;(-” AppleMenu ITEMS 


NEW.MENU FileMenu 

* File^ FileMenu TITLE 

Ø FileID FileMenu BOUNDS 

" Close;Quit^FileMenu ITEMS 


NEW.MENU EditMenu 

* Edit^ EditMenu TITLE 

0 EditID EditMenu BOUNDS 

* (Undo/Z;(-;Cut/K;Copy/C;Paste/V;Clear” EditMenu ITEMS 


VARIABLE DAName 60 VALLOT 
VARIABLE updStore 169 VALLOT 
X for ‘update appointments’ dialog 

VARIABLE updPtr 
VARIABLE msgPtr \ for storing the dialog pointers 
VARIABLE updRect 4 vallot 
VARIABLE hUpdList \ stores list handle 
VARIABLE listRows N total 8 of rows in list 
VARIABLE datim 10 VALLOT 

V 14 bytes for date-time record 
VARIABLE msgTxt 252 VALLOT 

\ 256 bytes for item text 


V ***** list manager support 
\ List Manager select flags. 
128 CONSTANT OnlyOne 


64 CONSTANT ExtendDrag 
32 CONSTANT NoDisjoint 
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16 CONSTANT NoExtend 

8 CONSTANT NoRect 

4 CONSTANT UseSense 

2 CONSTANT NoNilHilite 


\ Offsets into the List record 
12 CONSTANT IndentOffset 

36 CONSTANT SelF lags 

88 CONSTANT LDataHandle 


CREATE ArrayDim N Initially we will have an empty array. 
N We^1l add rows and columns later. 
Ø W, А Row-o. 
0%, \ Column-o. 
O W, \ Rowi. 
1 W, \ Column-i. 


: NewVList С rview databounds size wPtr - lhandle ) 
Ø  WXLDEF proc id 
swap \ window pointer 
0 \ Drawlt flag 
0 N HasGrow flag 
0 N scrollHoriz flag 
-1 \ scrollVert flag 
(CALL) LNew 


: MakeList ( rect vcell һсе11 «Ріг | 
lhandle cellpt rectbr rectt] – lhandle } 

rect @ $10001 + -> recttl 
rect 4 + @ $10010 - -> rectbr 
^ rectt] \ Pass rectangle. 
ArrayDim \ Pass bounds. 
vCell ^ cellpt W! 
hCell ^ cellpt 2+ W! 
cellpt N Pass cell size. 
wPtr 
NewVList -> lhandle 


OnlyOne NoNilHilite + 

\ Select only one cell at а time. 
lhandle 6 SelFlags + C! 

\ Don’t hilite empty cells. 
Thandle 


: readiline ( ^pfile string | pStr char - flag ) 
string -» pStr 
BEGIN 
*pfile 6 virtual сё -> char 
1 ^pfile +! 
char Ø= char 13 = OR Ø= WHILE 
1 +> pStr 
char pStr с! 
REPEAT 
pStr string - string c! 
char 


: open-dates-file 
* Dates? $open дур Ø< 
IF drop ^ Dates’ dup 
$create drop 
$open 
THEN 
РТО w! 


: fill-list ( | pfile theCell - ) 
0 listRows ! 
open-dates-f ile 
0 -> pfile 
BEGIN 
^ pfile msgTxt readiline WHILE 
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1 listRows 6 hupdList 6 call LAddRow drop call LSetCe11 
0 -> theCell THEN 

listRows 6 ^ theCell w! 
1 listRows *! 


д 


msgtxt count theCell hupdList @ call LSetCe11 : getText ( digPtr item string | iType iHdl iBox - string ) 
REPEAT digPtr item? ^ 1Туре ^ iHdl ^ iBox 
ГТО wê closef ile call GetDItem 
-1 Мірй 15% 6 cal] LDoDraw iHd! string call GetIText 
hupdList 6 call LAutoScroll string 
: write-list ( | len theCell offset - ) : setText ( digPtr item string | iType iHdl iBox - ) 
open-dates-f ile digPtr item® ^ iType ^ iHdl ^ iBox 
0 -> offset call GetDItem 
listRows 0 0 DO iHd! string cell SetIText 
Ø -> theCell i ^ theCell и! Р 
0 -> len 255 ^ len w! 
msgIxt ^ len theCell hUpdList e : setup-msg ( editDlg string | - string ) 
call LGetCe11 editDlg 8 string getText С year ) 
^ Теп wê -> len editDlg 9 string 3 + getText C month ) 
13 msgTxt len * c! editDlg 10 string 6 + getText С day ) 
1 + len editDlg 11 string 9 + getText С hour ) 
offset len msgTxt fID wê write editDlg 12 string 12 + getText С min ) 
len +> offset editDlg 13 string 15 + getText С sec ) 
LOOP 
0 msgtxt с! editDlg 3 string 18 + getText ( message ) 
offset 1 msgTxt fID w@ write ce 18 + string c! 
offset 1+ fID w@ setEOF 
fID wê closef ile ascii / dup string 3 * c! string 6 * c! 
: 32 string 9 + c! 32 string 18 + c! 
ascii : dup string 12 + c! string 15 + c! 
\ UserDraw procedure string 


N must use (call) instead of call and use glue code 
\ for saving registers and setting up Forth stack 


: parse-msg ( string | sPtr - } 


: UserDraw ( іһе010 theItem | iType iHdl rectbr гес 1 - ) string с@ 18 - string 18 * c! 
6 0 do 
theDig theItem ^ iType ^ iHdl ^ recttl string i 3 х + -> sPtr 
(call) GetDItem 2 sPtr c! 
^ rectt] (call) FrameRect sPtr cell stringtonum 
theDlg 24 + @\ visRgn of dialog window datim i 2* + w! 
hUpdList ё \ list handle loop 
(call) LUpdate detim w@ 1900 + datim w! 
N UserDraw procedure glue code : set-dig ( editDlg string | - ) 
V sets up local stack etc. editDlg 8 string setText С year ) 
editDlg 9 string З + setText C month 2 
CODE gUser editDlg 10 string 6 + setText ( day ) 
LINK Аб,8-512 С 512 bytes of local Forth stack ) editDlg 11 string 9 + setText C hour ) 
MOVEM.L Ай-А5/00-07,-САТ) ( save registers ) editDlg 12 string 12 + setText C min ) 
MOVE.L Аб,АЗ С setup local loop return stack ) editDlg 13 string 15 + setText C sec ) 
SUBA.L 8256,A3 С in the low 256 local stack bytes ) editDlg 3 string 18 * setText ( message ) 
CLR.L 01 ; 
MOVE.W 8CA6),D1 С theltem ) 
MOVE.L 10CA6),D0 ( theDialog ) : getMsg ( text | editD1g itemHit iTyp iHdl iBox 
MOVE.L 00, -САб) - string_or_zero ) 
MOVE.L 01,-САб) msgID Ø -1 call GetNewDialog -> е914019 
text parse-msg 
UserDraw editDlg text set-dlg 
07 itemHit call ModalDialog 
MOVEM.L (А72%,А0-А5/00-07 С restore registers ) ^ itemHit w@ CASE 
UNLK A6 1 ОҒ editDlg msgTxt setup-msoENDOF 
MOVE.L CA72*,A0 С return address ) 2 ОҒ С Cancel ) Ø ENDOF 
ADD.W %6,A7 С pop off 6 bytes of parameters ) ENDCASE 
JMP (Ай) editDlg call DisposDialog 


RTS 
END-CODE MACH 
: userEdit ( | theCell len - ) 


: update-cell ( string | theCell - ) Ø -> theCell 
0 -> theCell -1 ^ theCell hupdList @ call LGetSelect 
-1 ^ theCell hupdList 6 call LGetSelect IF 
IF 255 ^ len w! 
string count theCell hupdList e msgixt 1+ ^ len theCell hupdList 6 call LGetCel1 
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^ Теп w8 nsgtxt c! 
msgtxt getMsg ?dup IF 
updete-cel1 
THEN 
THEN 
nmChanged оп 


: userAdd ( | theCell - } 
* yy/mn/dd hh:mm:ss Your message - “ 
dup с@ 1% msgtxt swep cmove 
msgtxt getMsg IF 
0 -> theCell 
-] ^ theCell hupdList 6 call LGetSelect 
IF Ø іһесе11 hUpdList 6 call LSetSelect THEN 


1 listRows 6 hupdList 6 call LAddRow 
0 -> theCell 
listRows @ ^ theCell w! 
1 listRows *! 
msgtxt count theCell hupdList 6 call LSetCell 
-] theCell hUpdList 6 call LSetSelect 
hupdList 6 call LAutoScrol] 
THEN 
nmChanged on 


: userDelete ( | theCell - ) 
Ø -> theCell 
-1 ^ theCell hupdList 6 call LGetSelect 


IF 
1 ^ theCell w@ hupdList 6 call LDelRow 
-] listRows *! 

THEN 
nmChanged on 


: userList-handler ( | thePt thePort - ) 

^ thePort call getPort 

call frontwindow call setport 

^ thePt call getMouse 

thePt event-record modifiers + wê 
hUpdList 6 
call LClick 

IF € double click ) userEdit THEN 
thePort call setPort 


: CloseMe 
updPtr 6 call CloseDialog 


: QuitMe CloseMe ; 


: dialog-handler 
( itemHit dlgPtr | - ) 


itemHit CASE 
1 ОҒ CloseMe ENDOF 
2 OF userEdit ENDOF 
3 OF userAdd ENDOF 
4 OF userDelete ENDOF 


5 OF userList-hendler ENDOF 
ENDCASE 


: instal lupdPtr 
updPtr @ ?dup IF 
nmTask 6 2+ call SetWRefCon 
ELSE 
cr .” Couldn’t create dialog’ 
ABORT 


: installuserDraw ( pUser | iType iHd] rectbr rectt! - } 


updPtr 6 5 ^ iType ^ iHdl ^ recttl 
call GetDItenm 
updPtr 6 5 ^ iType wê pUser ^ rectt] 
call SetDItem 
^ гес] 16 280 updPtr 6 MakeList 
hUpdList ! 


: UndoMe ; 
: CutMe ; 

: Соруме ; 
: PesteMe ; 
: CleerMe ; 


: do-ebout 


128 0 CALL Alert DROP 


: do-epple  ( item? ) 


V item = 1 CAbout...2? 

item 1 = 

IF do-about 

ELSE 
Applemenu @ item# DAName CALL GetItem 
DAName CALL OpenDeskAcc DROP 

THEN ; 


: DO-FILE С item? - ) 


( handles selections from the file menu ) 
CASE 

1 OF CloseMe ENDOF 

2 OF QuitMe ENDOF 

ENDCASE 


: DO-EDIT С item? - ) 


( handles selections from the edit menu ) 
dup 1- cal! SysEdit С item? flag ) 
= IF 

CASE 

1 OF UndoMe ENDOF 

3 OF CutMe ENDOF 

4 OF CopyMe ENDOF 


5 OF PasteMe ENDOF 
6 OF ClearMe ENDOF 
ENDCASE 

THEN 


‚ nmBAR-handler € item® menuID - ) 


— 


CASE 

APPLEID OF DO-APPLE ENDOF 
FILEID OF DO-FILE ENDOF 
EDITID OF DO-EDIT ENDOF 
ENDCASE 

0 CALL HILITEMENU 


setup notify request with text in (msgTxt * 18) 


: sey- it 


nmPresent @ IF 
1 € mark ) 
0 С no Icon ) 
-1 С system beep ) 
msgixt 18 + С string to display ) 
-1 С remove request ) 
0 ( no refCon 2 
notify-request 
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5 call sysbeep 
HEN 


: get tine ( | time - secs ) 
^ time call readdatetime drop 6 


: get.next dete ( | len theCell secs - ) 


listRows @ 0 00 
0 -> theCell i ^ theCell w! 
255 ^ len w! 


msgTxt 1+ ^ len theCell hupdList @ call LGetCe11 


^ Теп w@ msgtxt c! 

msgtxt parse-msg 

datim call date2secs -? secs 
get_time secs u« IF leave THEN 


-1-» secs \ in case no date matches 


LOOP 
secs nmSecs ! 
nmChanged off 


: wait ( ticks | time - ) 
call tickcount ticks + -> time 
begin 

peuse 

call tickcount time › 

until 


: check. next. dete 
nmChanged 6 IF get next date THEN 
nnSecs 6 get time 
и‹ IF 
say_it 
60 wait 
nmChanged on 
EN 


: check_dialog_up 

updPtr ё wVisible + ce 

ø= IF write-list bye 
THEN 


: go.nm 
ACTIVATE 
fill-list 
(71 dialog-hendler modelessVector ! 
[^] nmmBar-handler menu-vector ! 
nmWindow dup call showWindow 
call selectWindow 
updPtr 6 dup call showWindow 
call selectWindow 
call DrewMenuBar 
begin 
PAUSE 
check. next. date 
check. dialog-up 
again 


: nmPresent? 

NMTrap# CALL GetTrapAddress 
UnkTrap# CALL GetTrapAddress 
= IF 0 ELSE 1 THEN 

nmPresent ! 


: start 


nmPresent? 
nmWindow ADD 
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nmWindow nmTask BUILD 


пиВаг ADD 
nmBar AppleMenu ADD 


AppleMenu 6 азс11 DRVR CALL AddResMenu 


nmBar FileMenu ADD 
nmBar EditMenu ADD 
nmBar nmTask mbar’ task 


updID updStore -1 call GetNewDialog 
updPtr ! 


installupdPtr 
[°] gUser instellUserDrew 


nmChanged on 
пиТазк go.nm 
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Listing 2: Resources for example СИРИ Rez format) 


resource 'DITL^ (2000, “date list”) ( 
( /* array DITLerray: 5 elements */ 
/* (1) */ 
(212, 328, 296, 392), 
Button ( 
enabled, 
“Exit? 


}, 
/* (2) */ 
(168, 328, 192, 392), 
Button ( 
enabled, 
“Edit” 


), 
/* [9] */ 
(200, 328, 224, 392), 
Button ( 
enabled, 
“Add...” 


), 
/* (4) */ 
(232, 328, 256, 392), 
Button ( 
enabled, 
“Delete” 


/% (5) */ 

(8, 8, 312, 312), 

UserItem ( 
enabled 


) 
); 


resource 'DITL^ (2001, “appt text”) ( 


( /* array DITLarray: 15 elements */ 


/* (1) */ 
(160, 256, 184, 320), 
Button ( 

enabled, 

“оқ” 


), 
/* [2] */ 
(160, 336, 184, 408), 
Button ( 
enabled, 
“Cancel” 


/* [3] */ 
(49, 10, 145, 410), 
EditText ( 
disebled, 
е” 
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), *Dete:^ 

/* (4) */ , 

(15, 275, 33, 295), /* (15] */ 

StaticText ( (16, 176, 32, 196), 
disabled, StaticText ( 
ығы disebled, 

), “at” 

/* [5] */ } 

(15, 235, 33, 255}, } 

StaticText ( ); 
disabled, 


resource 'DITL^ (128, “About Appts”) ( 


}, ( /* array DITLerrey: 2 elements */ 
/* [6] */ /* [1] */ 
(15, 129, 33, 149), (159, 82, 188, 151), 
StaticText ( Button ( 
disebled, enabled, 
| «J^ “Okay <>” 
/* [Т] */ /* [2] */ 
(15, 89, 33, 109), (35, 28, 128, 192), 
SteticText ( SteticText ( 
disebled, disabled, 
ud ad “Appointment reminder - \nNotification Man” 
), “ager example\n@ 1988 J. Lengowski / MacTu” 
/* [8] */ *tor^ 
(16, 58, 32, 86), ) 
EditText ( ) 
disebled, у: 
"s 
), resource “0100” (2000, “date list”) ( 
/* [9] */ (54, 38, 380, 446), 
(16, 101, 32, 127), noGrowDocProc, 
EditText ( invisible, 
disabled, goAway, 
е 0х0, 
), 2000, 
/* (10) */ “Appointments” 
(16, 140, 32, 167}, ); 
EditText ( 
disabled, resource “0106” (2001, “appt text’) ( 
“ë (48, 16, 248, 440), 
), dBoxProc, 
/* [11] */ visible, 
(16, 205, 32, 231), noGoAway, 
EditText ( 0x0, 
disebled, 2001, 
"^ “Edit Appointment? 
), ); 
/* [12] */ 
(16, 244, 32, 211), resource 'ALRT^ (128, “About Appts”) ( 
EditText ( (40, 40, 240, 280), 
disebled, 128, 
er ( /* array: 4 elements */ 
), /* [1] */ 
/* (131 */ Cancel, visible, silent, 
(16, 284, 32, 312), /* [2] */ 
EditText ( Cencel, visible, silent, 
disebled, /* [3] */ 
"S Cancel, visible, silent, 
), /* (4) */ 
/* [14] */ Cencel, visible, silent 
(16, 8, 32, 50), ) = 
SteticText ( ); Sel 


disabled, 
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Forth Forum 
Code Segments & Linker 


Code segments and a Mach 2 linker 
This month I'd like to report on some recent Mach2 im- 
provements: the new 2.14 version and a linker for kernel- 
independent applications that has recently appeared on the GEnie 
Mach2 roundtable. Since many of you don't have access to that 
BBS, I'll document the linker here, with some review of code 
segment structure, and put the code on the source code disk. 


Single-segment linker 

We have seen several examples - DAs, XCMDs, MDEFs - 
of Mach2 code that runs independent of the Forth multitasking 
kernel. Writing such code requires that the programmer write the 
setup code that is usually provided by the Mach2 system. For the 
examples that I gave in my column, the standard glue code for 
making a routine callable from outside Mach2 looked similar to: 
CODE prelude 

LINK Аб, ®-Nstack 

X Nstack bytes of local Forth stack 

MOVEM.L Аб-А5 /00-07, - CAT) \ save registers 

MOVE.L A6,A3 \ setup local loop return stack 

SUBA.L "Nlocal,A3 V in the low Nlocal stack bytes 

MOVE.L 8CA6),D8 N pointer to parameter block 

MOVE.L 00,-CA6) 


RTS \ just to indicate the MACHro stops here 
END-CODE MACH 


CODE epilogue 


MOVEM.L (А72%,А0-А5/00-07 \ restore registers 


UNLK A6 

MOVE.L САТ)+,Аб \ return address 

ADD .W 84 AT V pop off 4 bytes of parameters 
JMP CAB) 

RTS 


END-CODE MACH 


: my-forth-code 
С code to be called externally ) 


: ext.routine 
prelude my-forth-code epilogue 


After these definitions, the routine ext.routine may be called 
from the outside as if defined in Pascal as: 

procedure ext.routine (parameter:longint); 

begin 

( code to be called externally ) 

end; 

All we need in this case before calling our Forth code is to 
_ setup а local Forth stack maintained by the Аб register, save all 
the registers for safety, and create a loop return stack maintained 
by A3. 

In principle, a complete application can be created this way; 
however, some more setup is required. А simple one-segment 
application consists of two CODE resources: the jump table in 
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CODE 0 and the actual code in CODE 1. The structure of the 
jump table (JT) as given in IM II-60 looks like the following (in 
the case that the first entry in the JT corresponds to a routine in 


i шола 1): 
longint Above А5 size С 32 + length of JT ) 
А. longint Below А5 size (appl. and QD globals) 
8: longint Length of jump teble in bytes 
12: longint Offset from AS to jump table (32 ) 


16: Jump teble: 
—— Jump table entry *1 — 


word offset of routine 81 from beginning of 
segnent 
longint MOVE.W 81,-CAT) 


( push segnent 8 of routine on stack) 
word -LoedSeg 
— following jump table entries — 
— for routine 82...п, if necessery — 

When an application is launched, the CODE O resource will 
be loaded and the first JT entry executed. This will load the 
appropriate segment into memory and jump to the routine to 
which the first entry is pointing. Thus, a simple one-segment 
application would consist of a CODE 0 resource like above, with 
one single JT entry: 

$nnnn С entry address in CODE 1 segment ) 
С attention: segment starts at ) 
( beginning of resource * 4) 
$3F3C000 1 C MOVE.W 81,-(АТ7) 2 
$A9F0 


С LoadSeg 2 


CODE 1 would contain the actual code, written in Mach2. 

What are the advantages of creating single-segment Mach2 
programs? First of all, we can create very small applications. The 
smallest conceivable application, which does absolutely nothing 
but return, would comprise only 30 bytes: 


CODE 0: 
$00000028 C always $20 + lengthCJTO 2 
$00000200 С arbitrary ) 
$00000008 C length of JT; one entry ) 
$00000020 ( always ) 
$0000 ( entry address in CODE 1 segment ) 
$3F3C0001 ( MOVE.W 81,-(АТ) 2 
$A9FØ ( LoadSeg ) 

CODE 1: 
$0000 С first routine is at beginning of JT ) 
$0001 С one entry in this segment ) 
$4E75 С RTS D 


This program is enclosed on the source code disk as a 
curiosity. The file actually is 364 bytes long (Resource map etc.), 
which is still pretty small. 

А second advantage is that we have complete control over 
the way the application sets itself up. In particular, we could pass 
aroutine pointer to /nitDialogs to activate the Resume button of 
the system bomb box, or we might want to control the amount of 
calls to MoreMasters. 

The disadvantage of compiling applications under Mach2: 
Obviously we have to care about all the things that the kernel 
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normally does for us, like basic event handling, menu and menu 

bar setup, screen input/output, etc. Particularly, there are quite a 

few Forth words that may not be used anymore; regular readers 

of this column should be familiar with the rules for creating 

*kernel-independent code' that I' ve laid out a few times already. 
The Forth words that can be used include: 


1“ + +! A +> - -> 0« 0s O> 1+ 1- 2* 2+ 2- 2/ 2DROP 
2DUP 2OVER < <> > >BODY >R ?DUP (0 ABS AND 
ASCII C! C@ DROP DUP EXIT I I J LEAVE L EXT 
NEGATE NOT OR OVER PAD РСК R> В@ SWAP U< 
W! W@ ХОК ( (it's OK to use local variables) 


The following control and branching structures may also be 
used: 


IF ELSE THEN BEGIN WHILE REPEAT UNTIL 
AGAIN CASE ENDCASE OF ENDOF DO LOOP «LOOP 


Assembler, of course, may be used freely. 


Waymen Askey, of Palo Alto Shipping, has created a 
"linker' utility that compiles single-segment application using 
the strategy given above. We reprint his program іп listing 1 with 
his permission. This linker operates on a program which has the 
following structure: 


PROGRAM programname; 
( definitions not to be included in the final application 
such as constants, compiling words, etc. ) 


VAR 
( global variable declarations will be offset from A5 ) 


PROCEDURES 
( Forth words called by the top level word ) 


MAIN 

( top level word which is called on startup. ) 

( This word should call the setup procedures ) 
( MachSetUp and MacintoshSetUp ) 

( which are provided with the Linker utility. ) 
END 


The linker computes the ‘below AS’ size from the variables 
defined after the VAR statement, adding space for the Forth 
stacks, Quickdraw globals and various other things. The offset of 
the MAIN entry point into the code segment is calculated and the 
jump table set up. MakeJumpTable and MakeMain are the words 
that create the jump table and code segment 1. 

MachSetUp initializes the registers for Mach2 usage. Float- 
ing point (D7), parameter (A6) and return (A3) stacks are created 
above the current stack base in the application globals area. The 
A7 stack, starting at CurStackBase, remains unaffected. The 
application globals area is then cleared. 

MacintoshSetUp does the standard initialization calls to 
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_MoreMasters, _InitGraf,  InitFonts, _InitWindows, _Init- 
Menus, TElInit, InitDialogs, FlushEvents and  InitCursor. 

After these initialization calls, the main program may be 
entered. An example of a short program which creates a window 
and beeps is given in the listing. This program, too, is only 858 
bytes long (!!!). 

Mach 2.14 upgrade 

For those of you who haven't yet upgraded to Mach2.14, Ill 
briefly review the latest changes. 

1. CASE optimization: redundant instruction sequences of 


the type 


MOVE.L 00,-САб) 
MOVE.L (Аб )+,00 
are по longer generated. 


2. Local variable handling: the new release offers access to 
the local variable compiler with the words LALLOT and LP@. 
For example, a word might define a local 16-byte buffer in the 
following way: 


: EXAMPLE { | Г 12 LALLOT 1 muBUffer - ) 
CR .” Please enter your name " 


* muBuffer 16 EXPECT 
CR .” Hello ” ^ myBuffer SPAN 6 TYPE ; 


The local variable compiler can be further enhanced through 
‘local variable compiling words’; examples on how to do this are 
given on the 2.14 release disk. 

3. Disassembler: References to USER and global variables 
are now given with their Forth names. Disassembly speed has 
been greatly improved, which is particularly evident when exe- 
cuting IL ona Mac Plus or SE. 68881 opcodes are now supported, 
however, 68020-specific instructions not yet. 

4. New words: ASCII now takes up to four characters, for 
easy definition of resource types. 4+, 4-, 4*, 4/ have been added. 
a n SHIFT will shift a 32-bit word a by n bits. 

5. The trap list has been updated. 

Feedback dept. 

"Dear Jorg, 

I saw a discussion of accented character problems in the July 
MacTutor and thought I would throw in a few digressions on that 
matter. 

First, you and your readers might be interested to know that 
Apple has removed the scaron and zcaron characters from the 
new NTX PROMS against the recommendation of Adobe. These 
characters were not accessible from the keyboard, because they 
are uncoded, meaning that no ASCII value is assigned. The only 
Way to access them is via Postscript character names. The good 
news is that several new characters were added making the NTX 
almost compliant with the ISO 8859 character set that Adobe 
routinely supplies with all new fonts. (Apple removed the “y and 
"Y, юо). 

For those of you who want to see the unencoded characters, 
you can get at them with the following Postscript code and a 
download utility, if you have one of the new unprotected Adobe 


fonts or a late model Laserwriter Plus with v.3 PROMs: 
/Garamond-Light findfont dup length dict 
/newdict exch def 
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(1 index /FID 
ne( newdict 3 1 roll put ) ( pop pop )ifelse 
) Гога11 

[Encoding 256 array def 

Encoding Ø /Garamond-Light f indfont 

[Encoding get Ø 256 getinterval putinterval 

Encoding 127 /DEL put 

Encoding 129 /1slash put 

Encoding 130 /Lslash put 

Encoding 131 /eth put 

Encoding 132 /Eth put 

Encoding 133 /thorn put 

Encoding 134 /Thorn put 

Encoding 135 /onehalf put 

Encoding 136 /onequarter put 

Encoding 137 /threequarters put 


Encoding 138 /brokenbar put 
Encoding 139 /onesuperior put 
Encoding 148 /twosuperior put 
Encoding 141 /threesuperior put 
Encoding 142 /scaron put 

Encoding 143 /Scaron put 

Encoding 144 /zcaron put 

Encoding 145 /Zcaron put 

Encoding 146 /yacute put 

Encoding 147 /Yacute put 

newdict /Encoding Encoding put 
/IsoGeremond newdict definefont pop 
/IsoGaramond findfont 18 scalefont setfont 
15 250 moveto 


“аз4-.! 7%6-7% 
9 3 


Untonnaidly there is no way, at present, to get at these with 
templates in Fontographer, so you have to make your own 
composites, if you want to add these characters to PostScript 
fonts. | 

Best regards, Tim Ryan 

SourceNet 

P.O.Box 6767 

Santa Barbara, CA 93160 


Garamond) show 


PS: The standalone caron (7) is frequently found as ASCII 
character 255, one of the last four untypeable characters. It can be 
accessed using QUED, ... and MS Word if you enter the character 
using its ASCII value. 

By the way, I did get a Greek + Hebrew System from Apple- 
France via persistent phone calls. 

I've enclosed the first draft of an article that will appear in 
my forthcoming book “Тһе Macintosh Book of Fonts". If you're 
interested in reprinting the final draft when it's available, let me 
know. 


Thanks, Tim, for that interesting letter (I’ve enclosed your 
Postscript code on the source code disk). Now if all these 
characters were defined somewhere in the standard fonts, 
wouldn't that be nice? I always wondered why there were so 
many empty places in the font definition tables, seems like a 
waste of space to me... 

In the next issue we'll introduce - with other contributions 
from this side of the Atlantic - a very nice and powerful utility for 
changing keyboard definitions, so at least that problem can be 
overcome. Till then. 
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Listing 1: Mach 2. 14 single-segnment linker 


V 9 Waymen Askey c/o Palo Alto Shipping 
\ Reprinted with permission. - JL 


N Guidelines for use of the single-segment “linker.” 

V This utility is NOT meant to replace the 

\ standard Mach TURNKEY process. Its use Cet present) 
V is limited to creating small Cone-segment, less than 
\ 32K) programs which do NOT require the multi-tasking, 
\ 1/0, and auto event-handling support which the normal 
\ turnkey process supplies. 

\ Also, since this utility is being supplied free to 

\ Mach users, Palo Alto Shipping will NOT assume 

\ responsibility for support of the utility, nor 

\ will we be held responsible for any errors (bugs) 

\ which it may produce. 

\ It should, however, point the way for other 

\ compiler enhancements by users. The “bottom line” is 
\ that Mach can be used to create any type Cand size) of 
\ Macintosh application, DA, driver, INIT, etc. 

\ Waymen @ PASC 

( 


V The following words МАУ be used freely within the 
V stand-alone, “linked” epplication. 
\ 


| 81 ^ +) - 5 04 05 6› 1+ 1- 2 2+ 2- 
2/ 2DROP 2DUP 20VER < © = > BODY Ж ?DUP e 
ABS AND ASCII C! Ce DROP DUP EXIT I I^ J LEAVE 
L.EXT NEGATE NOT OR OVER PAD PICK R> Re SWAP 
Uc W! We XOR ( Cit’s OK to use local variables) 

N The following control and branching structures MAY 
\ also be used. 


\ 
IF ELSE THEN BEGIN WHILE REPEAT UNTIL AGAIN 
CASE ENDCASE ОҒ ENDOF DO LOOP +LOOP 


\ All assembler words may be used. 

\ The following compilation words MAY be used to 
\ create your application (but don’t attempt to 
\ compile them, they can’t be executed during the 
\ run-time of your finished application). 

: 4 VARIABLE CONSTANT USER CREATE DOES» 
,CODE CODE END-CODE ALLOT VALLOT , W, С, 
HERE COMPILE [COMPILE] IMMEDIATE SMUDGE LITERAL 
LAST MACH RECURSIVE Г ] 

\ Note, global variables may ONLY be used if you 

\ declare a VAR block. 


V [*] should be used with caution. 

\ Don't use it on words def ined outside of your 

V program block. 

\ If you wish to use EXECUTE, it may be redefined as 
\ 


CODE EXECUTE Са - ) 
MOVE.L САб 2+, Аб 
JSR САЙ) 
RTS 
END-CODE MACH 
\ ONLY the following MAC vocabulary words MAY be used. 
N Remember to use (CALL) instead of CALL. 


\ 

(CALL) A11 CONSTANTS used for the creation of user 
interface structures CCLOSEBOX, VISIBLE, etc.) 

If you define а VAR block, EVENT-RECORD (and all 
other system global variebles) пау be 

used аз а storage area only - events (and other 
information) will NOT automatically be posted 
there). 

\ These utilities may also be used. 

TRAP® TRAPLIST TRAPNAME 
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\ zzzzzzzzzz Can't Use These ============ 

\ Words which тау NOT be used!!! This is NOT а 

N complete list, just some of the more common words. 
\ You must NOT compile any word which is referenced 
N through Mach’s own jump table (words which compile 
\ а JSR ЖАЗ) instruction. 


\ 

CALL GLOBAL TERMINAL TURNKEY NEW.WINDOW ADD Cetc.) 
BUILD TASK ТАЅК-> BYE EVENT-TABLE PAUSE 

А11 1/0 such as KEY EXPECT EMIT .” TYPE Cetc.) 

« н %5 #) DEPTH 2SWAP CMOVE х / /MOD */MD */ 
Cif you are using a Mac II exclusively, you may substitute the 
new 32-bit math routines which came with the last Mach 
upgrades.) NO SANE words, NO TALKing words, 

№ I/O words. None of the “high-level” FILE words іп 

the MAC vocabulary. NO words which reference the 
multi-tasking kernel, NO 1/0 task words Ci.e. events 

MUST be handled explicitiy, you must create your own 
event-loop). 

А space for USER veriebles is reserved for your 

program, but all of them (except for the TIB value, 

S0, and RETURN_STK) ere initialized to zero. 

Consider USER variables аз just another global storage 
area. Words like BASE and CABORT) may be used; however, they 
will have NO effect on your program unless you specifically 
design the words to use then. 

) 


\ А simple, one-segment linker which may 

N be used (with restrictions) to create 

N small applications in high-level Forth. 

N Also allows you to create very small assemblu 

N language programs (mininum size about 40 bytes) 

V With slight modifications to the “linker? and the 
\ proper SetUp word, could also be used 

\ to create DA’s, FKEY’s, XCMD’s, and INIT’s. 

N – Waymen 

\ @ Palo Alto Shipping Company 


ONLY MAC ALSO FORTH DEFINITIONS 
DECIMAL 


$908 CONSTANT CurStackBese 


$434F4445 CONSTANT ‘CODE’ 
$4150504C CONSTANT ‘APPL’ 
$3FSF3F3F CONSTANT '????' 


21 CONSTANT Main€rr 
£10 CONSTANT EndErr 
1100 CONSTANT ProcErr 


$12344328 CONSTANT GoodStert 
$1234432F СОМЅТАМТ StartFlag 
$12344328 СОМЅТАМТ GoodEnd 


N The default stack end USER variable sizes 

\ to be used іп building the jump table. 

\ I^ve made the USER size lerger to allow 

V Гога 256 byte PAD 

512 CONSTANT USERSize С USER variables) 

14 CONSTANT TIBSize C plus STATUS) 
600 CONSTANT PaeremeterSizeC Аб & АЗ stacks) 
200 CONSTANT FPSize С FP stack) 

206 CONSTANT GrafSize С QD globals) 


$20 CONSTANT BL 
-1 CONSTANT TRUE 
$ CONSTANT FALSE 


VARIABLE VarEntry 

VARIABLE SegmentEntry 

VARIABLE MainEntry 

VARIABLE SegmentEnd 

VARIABLE ProgrenF lag 

VARIABLE ProgramName 28 VALLOT 
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VARIABLE JumpTable 20 VALLOT 


: -Leading ( addr cnt | whiteSpace - addr’ cnt’ ) 
\ Adjusts addr and cnt to “strip” leading spaces from a 
string. 
\ Addr is the starting character address, 
\ cnt is the original length. 
0 -› whiteSpace 
BEGIN 
addr whiteSpace + C@ BL = 
whiteSpace cnt < AND 
WHILE 
1 + whiteSpace 
REPEAT 
addr whiteSpace + 
cnt whiteSpace - ; 


: RemoveSpaces ( addr | cnt - } 
\ Given counted string at addr, remove trailing and leading 
\ spaces and repack string. 

addr COUNT -TRAILING addr C! DROP 

eddr COUNT -Leading -? cnt 

( addr’) addr 1+ cnt CMOVE cnt addr C! ; 


: Scan ( addr num delimiter | cnt cher - flag ) 
\ m input stream, placing characters into string at addr 
un 
\ num characters ere received or delimiter is found. 
N If delimiter is NOT found prior to num, return FALSE 
N else return TRUE. 
num 0» 
IF 
0 > cnt 
BEGIN 
0 WORD 1+ C6 -> char 
cher delimiter = NOT 
num cnt > АЮ 
WHILE 
1 + cnt char addr cnt + C! 
REPEAT 
cnt addr C! char delimiter = 
ELSE 
0 addr | FALSE 
THEN ; 


: PROGRAM ( | cnt scenFlag - ) 

N Gets program name end init’s linker variables. 
ProgramName 31 ASCII ; Scan -> ScanFlag 
ProgramName RemoveSpaces 


ProgramName C@ Ø= scanFlag 05 OR 
ABORT’ Must use ; to delimit program name!” 


0 MainEntry ! 0 SegmentEnd ! 0 VarEntry ! 
StartFleg ProgramFlag ! ; 

: CleerErr € errNum - ) 
ProgramFlag 6 XOR ProgramFlag ! ; 


‚ VAR С-) 
N Ensure that current VP offset from А5 is 
\ even, then seve it. 
VP @ 1 AND 
IF 
1 VALLOT 
THEN VP @ ABS VarEntry ! ; 


: Globals? (-) 
N Checks to see if а VAR statement wes made. 
VerEntry 6 0- 
ІҒ 
10 CALL SysBeep 
CR .” WARNING: No global variables were declared!” 


Q The Definitive MacTutor, Vol. 4 


THEN ; 


: THERE (C - 82 
N Ensures that HERE pointer is even, then 
\ returns HERE. 
HERE 1 AND 
IF 
1 ALLOT 
THEN HERE ; 


: PROCEDURES С - D 
ProcErr CleerErr 
?HERE SegmentEntry ! 4 ALLOT ; 


: MIN C - ) 
MainErr ClearErr 
НЕВЕ MainEntry ! ; 


: ED C - ) 
EndErr С1еагЕгг 
?HERE SegmentEnd ! ; 


: ZeroF lags С - ) 
0 ProgramFlag ! 0 VarEntru ! 
0 MainEntry ! Ø SegmentEnd ! ; 


‚ Belowb (C-n) 
N Calculates the Below АБ space Гог 
V the jump table. 

VarEntry 6 DUP 0- 

IF 

DROP GrafSize 

THEN 

USERSize + TIBSize + 

ParameterSize + FPSize + ; 


: MakeJumpTable € - handle f ) 
N hendle is to a generic, one-entry jump table. 


$00000028 JumpTable | NA Above А5 size 


BelowA5 JumpTeble 4 *! 


CR .” MekeJumpTeble error!” ABORT 
THEN 
-) JumpHandle 
JumpHandle ‘CODE’ Ø “ Jump Table” 
CALL AddResource 
CALL ResError 


IF 
ZeroF lags 
refNum CALL CloseResFile 
JumpHandle CALL DisposHandle DROP 
CR .” Link (0): AddResource error!” 
THEN 
MakeMain 
IF 


ZeroF lags 
refNum CALL CloseResFile 
JumpHandle CALL DisposHandle DROP 
CR .” MakeMain error!” ABORT 

THEN ` 

-> MainHandle 

MainHandle ‘CODE’ 1 * Main” 

CALL AddResource 

CALL ResError 

IF 
ZeroF lags 
refNum CALL CloseResFile 
JumpHandle CALL DisposHandle DROP 
MainHandle CALL DisposHandle DROP 


CR .? Link (10: AddResource error!” ABORT 


THEN 
THEN ; 


: CreateAppIFile ( | refNum - refNum or zero ) 


\ Remember to delete previously made files! 


0 -> refNum 
‘2722’ ‘APPL’ ProgramName 0 CreateFile 
DISK 4% we 0- 
IF 
ProgramName CALL CreateResFile 


\ Global variable space 
$00000008 ^  JumpTeble 8 +! 
\ Jump table length 


ProgramName CALL OpenResFile 
\ This logic returns either a valid refNum or zero, 
\ as OpenResFile returns a -1 if it can’t open the 


900000020 JumpTeble 12 + ! 


N Jump table A5 offset 


\ Calculate segment entry point 
MainEntry 6 SegmentEntry 6 4+ - 
С entry) JumpTeble 16 + И! 
$3F3C000 1 JumpTable 18 + | 

V MOVE.W #1,-CA7) 
$000 1А9Ғ0 JumpTeble 22 + И! 

\ -LoadSeg 
JumpTable 24 CALL PtrToHand ; 


: MekeMain € - handle f ) 
V Offset to first jump-table entry 
0 SegmentEntry 6 W! 
\ Only one jump-table entry 
1 SegmentEntry ё 2+ W! 


SegmentEntry @ C start of 
segment ) 
SegmentEnd 6 SegmentEntry ё - С length of segment ) 


CALL PtrToHand ; 


: Link ( refNum | JumpHandle MainHandle - ) 
\ Creates, then adds CODE segments 0 and 1 
-\ to file refNum 
ref Num 
IF 
MakeJumpTable 
IF 


ZeroF lags 
refNum CALL CloseResFile 
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file. 


DUP -1= NOT AND -> refNum 
THEN refNum ; 


: Error ( errFlag - ) 
N Checks for proper program headings 
errFlag GoodEnd XOR 


IF 
CR ." Missing: * 
errFlag $FFFFFFF@ AND GoodStert = 
IF 
errFlag $111 AND 
CASE 
MainErr OF .” MAIN * ENDOF 
Enderr OF .* ЕМ) “ ENDOF 
ProcErr OF  .^ PROCEDURES ” 
ENDOF 
( else) 
." MAIN, END and/or PROCEDURES * 
ENDCASE 
SE 
." PROGRAM * 
THEN 
." Statement(s)!^ ZeroFlags ABORT 
THEN ; 


: MakeApplication ( | refNum - ) 
ProgremFlag 6 ?Еггог 
CreateApplFile -» refNum 
refNum 
IF 
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refNum Link Globals? 
refNum CALL CLoseResF ile 
ZeroF lags 


CR .? CreateFile error 87 DISK 4 + W@ L_EXT 
ZeroFlags ABORT 
THEN ; 


\ in the linked program. Thus, the above utilities may be 
\ workspaced, used and/or enhanced at will. 

\ MachSetUp and MacintoshSetUp should appear as the 

\ first statements in your MAIN or LAUNCH word. 


CODE MachSetUp С - 2 

X Sets up stacks for high-level Forth. 

X Not needed if you work only in essembly language. 
MOVE.L CurStackBase , DØ 
MOVE.L 00,01 
ADD.L 8FPSize,Dd 
MOVE.L 00,07 X FP stack 
MOVEA.L 00,АЗ\ “loop?” stack 
ADD.L *ParameterSize, Dd 
MOVEA.L DØ, A6 \ parameter stack 
ADD.L *TIBSize,DÓ 
MOVEA.L 00,А44 USER variables 
MOVEA.L D1,A0 
MOVE.L А5,00 
SUB.L D1,00 
DIVU.W 816,00 
MOVE.W D2,D2 N “blocks” to clear 
SWAP.W DØ N bytes to clear 
N Init all globals, USER 
\ vars and stack area to zeros 
BRA.S 620 

616 CLR.L (A0)+ 
CLR.L (А 0% 
CLR.L (A0)+ 
CLR.L (АЙ) 

620 DBF 02,010 
BRA.S 640 

630 CLR.B (А0)% 

640 DBF 00,630 
N Although it can^t really be used, 
V here I set-up the (TIB) USER ver 
MOVE.L Аб, 24(А4) 
MOVE.L Аб, 4(А4) N 50 USER ver 
MOVE.L АЗ, 12СА4) \ RETURN_STK USER var 
RTS 

END-CODE MACH 


\ below A5 bytes to clear 


CODE MacintoshSetUp € - ) 

-MoreMasters 
-MoreMasters 
РЕА -4CA5) 
-InitGraf 
-InitFonts 
-InitWindows 
-InitMenus 
-TEInit 
СІВ. -CA7) 
-InitDialogs 
MOVE.L 8%0000ҒҒҒҒ,00 
-FlushEvents 
-InitCursor 
RTS 

END-CODE MACH 


\ From this point on (between the PROCEDURES and END 
N statement) is where you place your application code. 
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PROGRAM My Exemple; 
N The required and beginning statement in your program. 
V The application will be titled as whatever appears 
N between the PROGRAM statement and the delimiting 
V colon Cup to 31 characters). 
N Words defined here 
V will NOT be included in your application 
aute redef intion of CALL is just а reminder. 
CR i Don’t use CALL here, use (CALL) instead.” 


д 


0 CONSTANT NIL 
-1 CONSTANT InFront 
10 CONSTANT TenTicks 
30 CONSTANT HalfSecond 
VAR 
N А11 global variables used within the program MUST follow 
N the VAR statement. If you don’t include the VAR 
\ statement, а warning will be given during progrem link. 
V If you don’t use global variables Cor Mach system 
N globals), you may ignore the warning. 
VARIABLE DelayTicks 
VARIABLE BoundsRect 4 VALLOT 
PROCEDURES 
\ А11 subroutines must appear between PROCEDURES апа 
N MAIN. Only that code appearing between the 
X PROCEDURES and END statements will appear in your 
V finished application. 


: SetDelay Сп - ) DelayTicks ! ; 
: Beeper ( beepTime - 
HalfSecond TenTicks 
DO 
beepTime (CALL) SysBeep 
I SetDelay 
DelayTicks 6 (CALL) Delay DROP 
TenTicks *LOOP ; 
: MakeWindow C -a | returns а window pointer) 
BoundsRect 20 72 492 322 (CALL) SetRect 
NIL BoundsRect “ Beeper Window” VISIBLE 
NOGROW InFront NOCLOSEBOX NIL 
(CALL) NewWindow ; 


: ProgremLoop ( | windowPointer - ) 
NIL -> windowPointer 
MakeWindow -> windowPointer 


10 Beeper 


windowPointer 9= NOT 
IF 
10 (CALL) SysBeep 
windowPointer ” BYE^ (CALL) SetWTitle 
60 (CALL) Delay DROP 
windowPointer (CALL) DisposWindow 
THEN ; 
MAIN 
\ The program’s entry point must appear immediately 
\ after MAIN i 
‚ LAUNCH ( - 2 
\ Don’t attempt to use local variables in the 
X LAUNCH word. The stacks aren't created until 
N after MachSetUp. 
MachSetUp 
MacintoshSetUp 
ProgremLoop ; 
END С of program “My Example”) 
V This statement does error checking I 
N and creates the application. sel 
MakeApplication TN 


CR .C An application called “My Example” has been created.) 
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Forth Forum 


European Developers' Conference 


Letter from Europe 

Happy Holidays. As MacTutor is entering its fifth year, we 
see more and more activity on the “other” (my) side of the 
atlantic, and many great articles have been sent to my address 
which we just couldn't publish yet. Coincidentally, the first 
European developers' conference has just been held in Paris; so 
we decided to dedicate part of this issue to the European Mac 
developers' scene. 

FirstI would like to express my thanks to all of you who have 
contributed to this issue and waited patiently for your article to 
appear. We are looking forward to more great contributions from 
overseas - keep them coming in! 


European Developers' conference, Paris 

If Apple's figures are correct (9000 certified developers in 
the US and 1000 in all of Europe), quite a significant proportion 
of those 1000 showed up at the conference. The main lecture hall 
was packed with 600 people, and there was just not enough time 
to listen to all the talks or see all the exhibits. This report is 
therefore necessarily selective, but I hope I can give you an 
overview anyway. 

This being the first developers’ conference I attended and 
the first such event in Europe, I cannot draw any comparisons. То 
me it seemed rather focused on marketing rather than technical 
aspects of development. [Apple's developer support right now 
seems to emphasize commercialization of “almost-ready” proj- 
ects; more and more talented Mac programmers that I know start 
having difficulties getting certified at an early stage]. [Guess 
what Jórg; US Developer's feel the same emphasis by Apple US 
on marketing and completion of "almost-ready" projects. -Ed] 

The list of speakers included mainly people from Apple 
Europe, but also a few famous names from the outside scene. АП 
in all, it was a well-organized event, at a conference center in a 
park at the city limits of Paris, with good food included; one could 
meet quite a few people [for instance, long-standing MacTutor 
contributor Steve Prof. Mac” Brecher and I met for the first time 
in person] and learned a couple of new things. 

The main drawback of the conference was its lack of time. 
2 days packed with lectures and exhibits on the developers' fair 
changing twice a day (there were only 20 stands for 80 exhibits) 
was just too much, and Apple took a little too much time for its 
slick visionary presentations. Which were, anyway, interesting 
to listen to. Some highlights: “UNIX is an operating system 
neither my nor your wife would use - or want to” (Mike Spindler). 
""There is no artificial intelligence"; “А real personal computer is 
a computer you'd want to take to bed"; "When we'll finally 
succeed in replacing the mouse with a pen, those used to three- 
button mice will have to take saxophone lessons" (Jean-Louis 
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Gassée). However, to make room for those presentations which 
I'd file under "entertainment", the technical talks had to be 
distributed into two parallel sessions, and I couldn't split myself, 
so I had to miss quite a bit. 

Neil Minkley, of the European Developer Services Group, 
emphasized that international compatibility still left a lot to be 
desired; for instance, mostcharacter recognition programs won't 
deal with accented characters - a simple neglect on the part of 
developers who аге not used to thinking “multinational”. Lan- 
guage, he said, might be considered an attribute of a piece of text, 
just as script, font or style. That way one could greatly simplify 
hyphenation, spelling checkers, etc. The perspective of a Euro- 
pean market without trade barriers after 1992, should encourage 
this kind of development. Neil summarized his talk in one more 
visionary quote, saying we should not have to wait till then - why 
not 1989. 

Interesting to note was that French developers will finally 
get access to AppleLink. Not so hot: the access level will 
probably only allow for sending and receiving memos, all the 
other services won't be accessible for a while. Whatever sense 
that makes. 

We also had a chance to get some “first hand" information 
on the Mac IIx by Peter Orr, who made (involuntarily) a convinc- 
ing point against upgrading for Mac II owners. It's not quite clear 
to me how one can manage to squeeze a 30-minute talk out of a 
one-page press release, but he did. Atleast I learned nothing new 
compared to what I had read already, and simply a 68030 and 
68882 at 16 MHz didn't seem that revolutionary to me. An 
interesting question - which was not addressed - was if and when 
the Multifinder will finally require the PMMU. From all the 
promises about compatibility that were made at the conference, 
І can only hope-guess that we won't have to trash our Pluses and 
SEs for a while. [The Mac IIx in my mind is strickly a marketing 
gimick to take the heat off the introdudction of the Next machine, 
whichis vastly a better pricelperformance point than the Mac Их, 
at Apple's inflated prices. My guess is that the real Mac IIx, with 
the proper high end clock speed, will be introduced next year and 
that machine will have amuch better pricelperformance point in 
comparison to Next. So what is the point of buying the IIx now, 
if Apple already plans to up the clock speed in six months? -Ed] 

Very thorough presentations were given on the two main- 
frame connection products, MacAPPC and MacWorkstation. 
Fergus Murphy, who showed MacAPPC, outlined the IBM LU 
6.2 networking protocols and then described the intelligent 
APPC communication card developed by Apple in great depth. 
This card sits in a Mac II, contains its own 68000 and operating 
system and will provide the APPC network service to any 
Macintosh on the same Appletalk network. 
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Alain Andrieux presented MacWorkStation, the program 
that will provide a front end to any application running on a 
mainframe connected to the Mac by a network or serial link. With 
my programs still running on a VAX and having a full Mac “look 
and feel", this seems to be the ideal toy for me. Later, on the Apple 
Expo, I could watch two demos: one was an application espe- 
cially written for MacWorkStation, with menus, dialog boxes 
and window appearance controlled by the mainframe applica- 
tion, and one “plain vanilla” interface to a database where only 
few changes could be made to the program and therefore only text 
was displayed in various windows. Setup of the various Mac 
interface elements was amazingly fast, even though the main- 
frame connection was only at 1200 baud. 

Alain Andrieux also gave a talk about MPW 3.0, which 
should be - hopefully - available in France by the time you read 
this. The points that impressed me most at first glance were the 
new symbolic debugger, SADE, which allows source-level 
debugging with Smalltalk browser-like windows across differ- 
ent programming languages under MPW, and the perspective 
that tools (like compilers) will finally run in the background 
under Multifinder. As a whole, it was confirmed that the Mac 
system is moving towards 32-bit addressing, and distinction 
between user and supervisor modes. We’re looking toward some 
more compatibility headaches here... 

Speaking of compatibility, Jim Friedlander from Apple 
Cupertino gave a long list of do-s and don’t-s. I guess since there 
still exist some programmers who write directly into the menu 
bar, such talks are justified. A couple of things in the discussion 
were interesting to note: The old Graf3D library won’t be 
supported anymore (who would have guessed?), the SANE 
engine won’t be speeded up much, they still think (or at least they 
say) precision is more important than speed, and Macintalk won't 
exist for languages other than English unless one of the foreign 
developers writes another version. 

With all the do-s and доп t-s, I missed the why-s. Developer 
guidelines seem to have a way to be stated rather than justified. 
Now, since modern software technology is largely object-ori- 
ented, and object orientation has to do a lot with information 
hiding, I kind of understand Apple’s way of thinking - to hide 
some of the information behind the developer guidelines that is 
considered “too dangerous” for the lowly “restuvus”. Rest as- 
sured that MacTutor will continue to try its best to break this 
information barrier. [The same thing happened in the Apple П 
world. After the days of Steve Wozniack hauling piles of loose- 
leaf documentation to user group meetings, Apple went through 
aperiod of denying the technical details of the machine, asserting 
that the unwashed masses didn't need to know all those gory 
details, and that revealing them would somehow tarnish the 
image of the appliance computer. When the Woz came back into 
the company, and the Apple IIgs was introduced, a lot of that 
nonsense went by the wayside. -Ed] 


Developers’ fair 
Parallel to the conference, an exhibition was held to give 
participants a chance to show their products. Well, at least for 
three hours. Since space was so limited, each exhibit was shown 
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only half a day, then someone else took over the booth. I was able 
to see at least some things. 

The Macintosh with its easy localization is especially 
adapted to a multi-lingual environment like Europe, and there 
were numerous examples of products making use of these prop- 
erties. 

Winsoft - our Grenoble local heroes - showed their multi- 
lingual multi-script word processing system, Wintext. With a 
word-processing functionality somewhere between MacWrite 
and MS Word, this program will allow you to mix left-to-right 
and right-to-left writing, e.g. in combined English/Arab texts. On 
top of that they added an equation editor for scientific texts, and 
spreadsheets that can be placed into the text similar to Ragtime. 
The whole program is a wonderful example of what MacApp can 
do in the hands of acompetent person. Kamel Gaddas, one of the 
creators of Winsoft, shared his MacApp experience in his confer- 
ence presentation. 

Unfortunately, Wintext is copy-protected, and in a stupid 
way: even when installed on a hard disk it will ask for the master 
disk on each launch. Sorry to say, much as I'd like to buy the 
program, they won’t get my money for a while. 

[Note on the side - on copy protection, my favorite subject: 
while last year the standard answer was still ‘well, in the US we 
might be able to do without copy protection, but for France there 
is no other way’, this year we could hear ‘well, in Europe we 
might be able to do without copy protection, but for the middle 
East markets there is no other way’... OK, so the targets are 
shifting. Let's hope they disappear]. 

AllPage was another multi-lingual word processing/ desk- 
top publishing system by a company from Israel. Interesting 
feature: any selection, comprising text and graphics, can be 
copied as a picture and then pasted and re-sized. 

Artificial intelligence (or whatever runs under this name) 
was represented in several exhibits: Procyon Research from 
Cambridge (UK) presented its Common Lisp implementation, 
which Expertelligence will distribute as a replacement of Exper 
Common Lisp. They distributed a very thorough introduction 
brochure and a demo diskette with a HyperCard stack. POP-11, 
the new AI programming language developed in Edinburgh and 
Sussex, was of course presented in its Mac implementation, 
AlphaPOP. Texas Instruments showed their Mac II-based AI 
workstation, microExplorer. 

Mainstay, the makers of VIP, Think ‘n Time, and other 
things, presented MarkUp, their new approach to text revision; 
sort of an electronic “red pencil”. This is a system where a group 
of people can share a text document and make their comments on 
transparent “layers” which can be later selectively displayed on 
top of the document. So Joe can type a text, then have Debbie and 
Al revise it, later look at their comments on top of his text 
independently, change the text, make his own comments, etc. 
Comments can be entered into the text by typing or by using a set 
of graphics tools. Of course, color is supported. A pretty unique 
idea, and hopefully a success. 

One particularly interesting contribution was an image 
processing application for microscopy Optimage, developed in 
Paris by university researchers and now being commercialized. 
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It is the first program that I'm aware of оп the Mac that allows 
digital filtering, Fourier transforms, particle detection and count- 
ing, or size determination of objects in microscopic images. 


Apple Expo 1988 

The annual Paris Apple Expo was held during and after the 
conference. This time, the exposition hall, an old glass-steel 
construction, had been entirely transformed into a giant Mac II. 
10-feet high floppies greeted the visitors in front of the building 
(how many gigabytes on that one?), and the - nonfunctional - 30- 
by 40- foot monitor on the outside served as a cloakroom. In the 
belly of the Mac II, the usual exposition come-and-go. Interest- 
ing the stand of Informix, in the form of a giant spaceship, where 
they introduced the long-awaited "hyper-spreadsheet" Wingz; 
this time they were announcing shipping in November. Vapor- 
ware special was the Gigatape, a 1.2 Gbyte SCSI tape backup 
which was supposed to work with DAT cassettes. When I asked 
for a demo, they said *we're still working on the driver, but it'll 
be ready Very Soon". Oh well. 

Apple occupied - naturally - a lot of floor space, and many 
of the more innovative applications were displayed on their 
stands; for instance a Labview-like data acquisition system, 
Personal Writer, a handwriting recognition system using a dig- 
itizer tablet, tons of educational HyperCard stacks, among them 
asystem that will automatically find the best subway connection 
between points A and B in Paris - and also tell you how long it'll 
take (usually too long). 


This year a contest was held; the Apple Trophy was awarded 
to seven programs selected by a jury from Apple France. 23 
programs were on the short list, and I was promised to get a copy 
of that list so we could print it here; alas, it never arrived before 
our deadline (unless David receives a link from Apple France 
directly, in which case it might be printed after all). ГІ just 
proudly mention that one of the members of our local Mac club, 
Yves Baulac, was among the prize winners with his geometry 
program, Cabri Geometre. The other six were Fileguard by 
Olivier Merenne, a hard disk protection/encryption facility that 
will protect your documents transparently; Hyperpage by Ber- 
nard Meunier, a page layout XCMD for HyperCard; Emploi du 
Temps, a planning utility by Jean-Luc Deleage; two medical 
utilities, Hypermed by Almanza and Thesaurus Urologie by 
Lardennois; and a graphing program, page de Graphe by Robert 
Elbeze. 

Otherwise, the usual exhibitors showed their usual products 
(hello, Microsoft; bonjour, ACI). Most of the real new stuff had 
already been shown at the developers’ fair. It was fun, anyway, 
to spend some time with friends at the MIDI stand. 

Just as I write this, one day before the deadline, I’ve received 
the final release of Mach 2.14, where a lot of things have been 
added even with respect to the beta version. Finally, the editor 
allows you to PRINT your text as well! 

Next month it's back to Real Forth again. Till then. 


Cod! 


ED, 
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The Workstation Mac 
Tips for Engineering Applications 


Introduction 

With the advent of the Mac 2 and many third party Macin- 
tosh speed enhancers many engineers will now consider using 
the Macintosh for serious computation. Many of these engineers 
are currently using mainframe computers where the graphics 
environment is primitive or nonexistant and where CPU time is 
expensive and has little to do with turn around time. The purpose 
of this article is to give a few pointers in BASIC and FORTRAN, 
the languages with which engineers will initially feel most 
comfortable, on how to make effective use of the Macintosh for 
both graphics and speed. 

Many engineers have heard that programming on the Mac is 
difficult and unlike mainframe programming. This is true if the 
end result is a commercial product. Making a program user 
friendly may cause simple code to grow by more than an order of 
magnitude. Using the various Macintosh toolbox routines re- 
quires the learning of a new language and a new way of thinking. 
However ordinary engineering applications are quite easy to 
program on the Mac - in fact even easier to program than on a 
mainframe or other micro - because of the user friendly environ- 
ment, superior editing tools and virtually instantaneous feed- 
back. 

This article will show how engineers can modify ordinary 
programs, written in FORTRAN or BASIC, which generate 
numerical output and enhance these programs with the addition 
of a few lines of code so that they can serve as input drivers to 
professional commercial graphics software. In this way their 
numerical output can easily be converted to professional quality 
graphs and charts with little effort. They will discover, as I did, 
that instantaneous graphical feedback will not only help them 
convey their engineering message to others quickly but will also 
challenge them to modify theiroriginal program to get even more 
useful information. In addition, techniques for generating ran- 
dom numbers on the Mac will be discussed so that engineers can 
see how easy itis to perform monte carlo and statistical analysis. 
Finally, for those engineers wanting to run more complex prob- 
lems on the Mac in BASIC, tips will be given on how to speed up 
program execution tiime with minimal changes to the program. 

Plotting 

The powerful graphic commands in MS BASIC and the 
access to the Macintosh toolbox in MacFortran permit the devel- 
opment of plotting packages in those respective languages. 
However, rather than re-inventing the wheel, it is better and 
much easier to use a very powerful commercial graphics package 
for engineers that already exists - Cricket Graph. The purpose of 
this section is to show the few lines of code are necessary to add 
to existing engineering programs so that the resultant output 
data, whether generated in BASIC or FORTRAN, can be trans- 
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ferred to Cricket Graph. 

Cricket Graph requires it's numerical input to be in a tab 
delimited format. Unfortuneately MS BASIC writes data to a file 
in comma delimited format. The simple fix to the problem is to 
have BASIC write it's output to the screen for viewing purposes 
and to also write the output to the Macintosh clipboard for 
eventual pasting into Cricket Graph. Listing 1 presents a sample 
BASIC program which computes the expressions у=Р and z=i3 
for values of iranging between 1 and 10. The resultant output is 
written to both the screen and clipboard. 

OPEN *CLIP:*FOR OUTPUT AS 81 

FOR 1=1 TO 10 

ү=1*1 

7=1^3 

PRINT I,Y,Z 

WRITE 81,1,Ү,7 

NEXT I 

CLOSE 81 

Listing 1 - Writing Output to Clipboard in BASIC 

The code in boldface can be added to any program so that 
output can be written to the clipboard in tab delimited format. 
The next step is to quit BASIC and then open Cricket Graph and 
finally to usethe paste command to import the data. The resultant 
line plot, developed with Crickett Graph and slightly enhanced in 
MacDraw, is shown in Fig. 1. 

Figure 1 - Using Cricket Graph to Plot BASIC 
Output 
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With Cricket Graph the ranges on the abscissa and ordinate 
сап be changed quickly by double-clicking on the axis of interest. 
In addition, the BASIC data can be viewed in log-log form by 
simply choosing the log option in Cricket Graph. Grids can be 
added for additional readability. Figure 2 shows the same BASIC 
data viewed in gridded log-log format. 

A FORTRAN program can also be modified so that its ouput 
can also be placed in a tabbed delimited format. This is easier to 
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LOG-LOG DISPLAY 
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Figure 2 - BASIC Output Viewed in Log-Log 
Format 

do in FORTRAN than in BASIC because it is possible to write 
data to a sequential file in tabbed delimited format. In order to 
illustrate the technique let's consider the Fourier Series represen- 
tation of the periodic square wave shown in Fig. 3. 

Figure 3 - Fourier Series Representation of 

Periodic Square Wave 
f(x) 
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An infinite amount of terms would yield a perfect represen- 
tation of the square wave whereas a finite number of terms would 
approximate the square wave. This effect is known as Gibbs 
phenomenon. Listing 2 presents a FORTRAN program which 
computes the first three terms of the periodic square wave Fourier 
Series and also writes the output to both the screen and also to a 
sequential file called "SAM". 

REAL L 

CHARACTER®1 TAB 
ТАВ-7709" 
OPENC1,STATUSx NEW?’ ,FILEz^SAM?) 
L=.5 

PI=3.14159 

С1=4. /PI 

00 10 Х-й,1,.01 

F 1=C 1*SINCPI*X/L) 

ЕЗ-Ғ 1*C 1*SINC3. *PI*X/L)/3. 
F5=F3+C 1*SINC5. *PI*X/L)/5. 
WRITEC9, *)X,F1,F3,F5 


WRITEC1,972X, TAB, F 1, TAB, F3, TAB, FS 
97 FORMATCF8.3,A1,F8.3,A1,F8.3,A1,F8.3) 
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10 CONTINUE 
CLOSEC 1) 
PAUSE 


END 
Listing 2 - Writing Tabbed Delimited Output to 
File in FORTRAN 

The boldfaced statements in the above listing can be added 
to any FORTRAN program to write the output data, in a tabbed 
delimited format, to a sequential file. The sequential file can then 
be directly opened by Cricket Graph for plotting. For this 
example the resultant Cricket Graph output is displayed in line 
chart form in Fig. 4. 

Figure 4 - FORTRAN Output Displayed in Cricket 

Graph 
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Random Numbers 

Random numbers play an important role in engineering 
applications. They form the cornerstone of monte carlo and 
statistical analysis. In BASIC, uniformly distributed random 
numbers are available with the RND statement. Other random 
distributions can be constructed from the uniform distribution. 
For example, since the RND statement creates a uniformly 
distributed number between O and 1 with variance 1/12 and mean 
.5, a gaussian distributed random variable with variance 1 and 
zero mean can be constructed, according to the central limit 
theorem, by adding 12 uniformly distributed numbers together 
(12 times 1/12 is one) and subtracting 6. Therefore the following 
BASIC statement generates an approximate Gaussian distrib- 
uted random variable with zero mean and unity standard devia- 
tion. 

X=RND+RND+RND+RND+RND+RND+RND+RND+RND+RND+RND+RND-6 

The distribution is approximately Gaussian since the maxi- 
mum and minimum values of the distribution are +6 rather than 
+e. If the approximate Gaussian number generator is in a 
program inner loop and computer running time needs to be 
enhanced, fewer terms can be used in the above expression to 
speed up the program. For example, a six term approximate 
Gaussian number generator with unity variance and zero mean 
can be constructed from 

X= 1. 414*(RND+RND+RND+RND+RND+RND-3) 

In this case the maximum and minimum values of the 
approximate distribution are +3 rather than +e. 
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FORTRAN, unlike BASIC does not provide a uniform 
random number generator. However an efficient random num- 
ber generator can be constructed in FORTRAN by making one 
toolbox call. TOOLBX(RANDOM) generates a uniformly dis- 
tributed integer between +32768 quickly. Listing 3 presents a 
FORTRAN program which, by using the above toolbox call, 
generates approximate gaussian random numbers and then puts 
the numbers into bins so that a probability density function can 
also be constructed. 


INTEGER BIN, RANDOM, SUM 
INTEGER*4 TOOLBX 
DIMENSION НС 10000 ),Х( 10000) 
PARAMETER СРАМ№О0И=2 /86 142006 ' ) 
CHARACTER*1 TAB 
ТАВ=2 ^09' 
ОРЕМС2,ЅТАТИЅ= ^NEW ^ ,FILEz "SAM" 
XMAX-6. 
XMIN--6. 
RANGE=XMAX-XMIN 
ТМР= 1/SQRT(6.28) 
N= 1000 
ВІМ-50 
00 10 1-1,М 
SUM=8 
DO 14 Ј=1, 12 
IRANZTOOLBXCRANDOM ) 
SUMzSUM* IRAN 
14 CONTINUE 
XCI228UM /65536. 
10 CONTINUE 
00 20 1=1,BIN 
НСІ2-0 
20 CONTINUE 
00 30 1-1,М 
Ke INTCCOCCID-XMIND /RANGE )*BIN)+.99 
IFC K¢1)K=1 
ТЕСКУВІМЖ=ВІМ 
H(K =H(K)+1 
30 CONTINUE 
00 40 K=1,BIN 
PDF=(H(K)/N)*BIN/RANGE 
AB=XMIN+K*RANGE/BIN 
ТН=ТМРЖЕХР(-АВЖАВ /2 . ) 
WRITEC9, * AB, PDF, TH 
WRITE(2,97 AB, TAB, PDF , TAB, TH 
97 FORMAT(F8.3,A1,F8.3,A1,F8.3) 
40 CONTINUE 
CLOSE(2) 
PAUSE 
END 


Listing 3 - FORTRAN Program Illustrating 
Random Number Generation 
The highlighted terms are those statements which are re- 
quired by any FORTRAN program to generate uniformly 
distributed or gaussian distributed random numbers. Here X(I) 
is the resultant gaussian distributed number. In this particular 
program 1000 random numbers are calculated. The accuracy of 
the random number generator is illustrated by viewing the 
program output, shown in Fig. 5, which compares the sampled 
probability density function to the theoretical bell-shaped curve. 
Speeding Up BASIC Programs 
In a previous issue MacTutor issue! it was shown how the 
transient response of a sixth order Butterworth filter could be 
simulated in FORTRAN using the second order Runge Kutta 
method for integrating the six differential equations. A block 
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Figure 5 - FORTRAN Generates Gaussian 
Distributed Random Numbers Accurately 


diagram of the Butterworth filter is repeated here for convenience 
іп Fig. 6. Here the “1/5” terms represent integrations. 


Figure 6 - Sixth Order Butterworth Filter 
The resultant six first order differential equations, which can 


be obtained from Fig. 6, are: 
х(1) = x(2) 


х(2) = x(3) 

x(3) - X(4) 

x(4) = x(5) 

x(5) = x(6) 

(6 $ x-x(1) Rel 2 ans) 840) . 84x(5) Е a, x(6) 

x(6) = = = 5 5 s > 
Š оф % % 


A BASIC program which can integrate the above differen- 
tial equations is shown in Listing 4. 

DIM X(6),X0LD(6),XD(6) 

START=TIMER 

B1=3.86:B2=7.46:B3=9.13:B4=7.46:B5=3.86:B6=1:W0=50 

XIN=1 

ORDER=6 

FOR I=1 TO ORDER 

XC1)=8 

NEXT I 

Т=0 

H= ,0005 

S=0 

BEGIN: 

IF Тэ-.5 GOTO FINISH 
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S=S+H 

FOR I=1 TO ORDER 

XOLD(I)=X(I) 

NEXT I 

GOSUB INTEG 

FOR I=1 TO ORDER 

XC(I)=X(I)+H*XDC(I) 

NEXT I 

T=T+H 

00508 INTEG 

FOR I=1 TO ORDER 

Х(1)=.5*(Х010(1)+Х(1)+Н®Х00С1)) 

МЕХТ 1 

IF $›.004999 THEN 

9-0 

PRINT Т,ХС1) 

END IF 

GOTO BEGIN 

FINISH: 

PRINT TIMER-START 

WHILE INKEY$-^"^:WEND 

INTEG: 

XDC 122XC2) 

Х0(22-Х(3) 

Х0(32-Х(4) 

Х0(42-Х(5) 

Х0(52-Х(62 

Х0(62-(%0-62%(ХІМ-В5%Х(62/(М0-52-В4%Х(52/(40742-83%Х(42/ 
(W0^3)-82*X(32/CW0^22-B 1*X C25 /W0-X( 1))/B6 

RETURN 

END 


Listing 4 - BASIC Simulation of Butterworth Filter 


We can see from the listing that the integration step size, Н, 
is .0005 sec. The running time for this program in interpretive 
MS BASIC is 229 sec on a Macintosh. Halving the step size or 
doubling the simulation time will double the running time. The 
program can be speeded up by using the MS BASIC Compiler 
and the resultant running time will decrease to 56 sec. Other 
methods can also be used to further enhance speed. For example 
the compiler and interpreter assume that all arrays are dynamic. 
However we can tell the compiler, but not the interpreter, that the 
arrays are static (as long as we aren't going to redimension 
statements during the program) and significantly decrease the 
running times. In addition, making loop parameters integers, as 
is commonly done in FORTRAN, rather than default single 
precision real numbers will also enhance running time - espe- 
cially with the compiler. Converting real numbers to integers can 
easily be accomplished in BASIC by adding a percent sign to the 
variable. Finally eliminating repeated calculations of constants 
from loops will also speed up the program. For example, the 
derivative XD(6) has many such constant computations which 
can easily be moved to the beginning of the program without 
destroying the readability of the code. The faster running BASIC 
program is shown in Listing 5. 

DIM XC62, XOLDC6), XDC6) 

START=TIMER 

В1=3.86:В2=7.46:В3=9. 13:B4=7. 46:B5=3 .86:В6=1:10=50 

XIN=1 

ORDERS=6 

М02= 0:16 

М03= 02:16 

М04= 00306 

М05= 04:15 


М06= 05:16 
FOR 15=1 TO ORDERS 
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XCIS228 

NEXT 1% 

Т=0 

H= .0005 

S=0 

BEGIN: 

IF Т›=.5 GOTO FINISH 

S=S+H 

FOR IS=1 TO ORDERS 

XOLDCIS2sXCIS) 

NEXT 14 

00508 INTEG 

FOR 1Я=1 TO ORDERS 

XCIS22XCIS2*H*XDCIS) 

NEXT 1% 

Т=Т+Н 

GOSUB INTEG 

FOR 1821 TO ORDERS 

XCIES 22, 5* CXOLDCIS2*XCIS 2 *H*XDC IR 2) 

NEXT 1% 

IF 5» .884999 THEN 

5-0 

PRINT T,XC1) 

END IF 

GOTO BEGIN 

FINISH: 

PRINT TIMER-START 

WHILE INKEY$s^^:WEND 

INTEG: 

ХОС 1)=Х(2) 

ХОС2 )=Х(3) 

XDC322XC42 

XDC422XC5) 

XDC522XC6) 

XDC622496* CXIN-B5*2XC62/495-B4*XC52/464-B3*X (42 /№03- 
Vai ыы ды 


END 
Listing 6 - Faster BASIC Program 


The terms that were changed to speed up the program are 
highlighted. Table 1 documents the speedup enhancements. 


Condition Interpreter Compiler 
Nominal 229 sec 56 sec 
Make Arrays Static 229 sec 42 sec 
Use Integers in Loops 211 sec 26 sec 
Move Constant Computations 120 sec 22 sec 
Out of Loops 


Table 1 - Improving Speed of BASIC 

We can see from Table 1 that there is a big payoff in using 
static arrays and integers when using the compiler. On the other 
hand, moving constant computations out of loops is more effec- 
tive, in this case, when using the interpreter. For this example we 
can see that the net speed-up in being careful and using the 
compiler, rather than the interpreter, is more than a factor of 10 
with only minor modifications to the original code. The best 
policy is to first get the programmed debugged and running using 
the interpreter because errors can be found and corrections can be 
made virtually instaneously. The tips for speed enhancement can 
then be applied when the program is checked out and is ready to 
be compiled. 
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Introduction 


MATLAB is an interactive program to help with scientific 
and engineering numeric calculations. Although it was originally 
written in FORTRAN for mainframe computers, a second gen- 
eration MATLAB was rewritten for smaller computers such as 
the Sun Workstation and the VAX computer. In the last few years 
aspecial version of MATLAB was developed to run on М5 DOS 
compatable PC's with math coprocessors. Typical uses for 
MATLAB are general purpose numeric computation, algorithm 
prototyping and solving special purpose problems with matrix 
formulations that arise in disciplines such as automatic control 
theory, statistics and digital signal processing. MATLAB is 
now available for the Mac II or for any Mac souped up with a 
68020 accelerator board and a 68881 math coprocessor. For 
engineers this lends legitimacy to the claim that the Mac II is 
actually a workstation. 

Unlike FORTRAN on the MAC, MATLAB is not really 
designed to make executable code (i.e. “double clickable” appli- 
cations). As with interpretive BASIC, the MATLAB application 
is required on the disk to execute any file previously generated. 
Unlike BASIC, MATLAB is very fast because of the highly 
efficient algorithms. MATLAB allows engineers to solve prob- 
lems almost as they are written mathematically and in addition 
allows easy access to libraries of some very powerful software. 
Some have called MATLAB “APL without the pain”. The Mac 
version of MATLAB takes full advantage of the Mac interface. 
This also means the MATLAB output can easily be incorporated 
into reports and presentations making MacMATLAB far more 
useful than the DOS version. 


Matrix Examples 
Matricies can be entered either in the MATLAB editor or by 
the carrot prompt by using brackets to define the matrix and 
semicolons to separate matrix rows. For example, by entering 


»А-(1 2 3;4 5 6;7 8 0] 


we get the MATLAB output on screen as 


А = 
12 3 
4 5 6 
7 8 0 
If we want to find the transpose of matrix А we simply type 
at the prompt 
»B=A’ 


where the ‘ indicates transposition The resultant screen 
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Taking the matrix inverse of A is simple as typing 
»inv(A) 


which yields the screen output (nearly instantaneously) 
ans = 


-1.7778 0.8889 -0.1111 
1.5556 -0.7778 0.2222 
-0.1111 0.2222 -0.1111 


Many other matrix and linear algebra functions are available 
with MATLAB. Ofcourse, many engineers have these functions 
built into their FORTRAN libraries - so why use MATLAB? 
Let’s do more examples to see why! 


Polynomial Example 


Suppose we had two polynomials and we wanted to multiply 
them and find the roots of the resultant expression. If the two 
polynomials were 

х2+3х+2 and х2+х-12 


we would define the polynomials in MATLAB by typing 
»А=[1 3 2]; 


»В=[1 1-12]; 


where the polynomials are expressed as vectors where the 
vector elements represent the polynomial coefficients in de- 
scending order. We can multiply the 2 polynomials algebraically 
in MATLAB by using the convolution function or 
»C=conv(A,B) 


which yields 
»C = 
1 4 -7 -34 -24 


The screen output displays the coefficients of the resultant 
polynomial in descending order. This means that the product of 
the 2 polynomials is given by 

Х4--4х3-7х2-34х-24 


To find the roots of the resultant polynomial we simply type 
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»roots(C) 


which yields the 4 roots as 
ans » 


3.0000 
-4.0000 
-2.0000 
-1.0000 


Still not impressed with MATLAB? Let's look at more 
examples. 


Plotting 


Unlike FORTRAN, plotting functions come built into 
MATLAB. If we wanted to plot 

y=sin(x) and z=.01x? from -15 to 15 in increments of .05 only 
the following 4 MATLAB statements would be required 


»Хж-15:.05:15; 
»y=sin(x); 

»2 =Х.^2/100; 
»ріо{(х,у,х,2) 


The unenhanced screen output for such а set of commands 
appears in Fig. 1. Of course since MATLAB grpahical output is 
in the PICT format it can be copied to the clipboard and pasted 
into any Macintosh application. 
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Figure 1 - Plotting With MATLAB is Easy 


The graph can be embellished within the MATLAB envi- 
ronment (with features similar to Cricket Graph) or copied onto 
the clipboard and pasted into MacDraw for further enhancement. 

If we wanted to show that a 5 term Fourier series expansion 
for a square wave is accurate (Gibb's effect) we only need the 
following 3 lines of MATLAB code. 


»t = 0:.1:10; 
эу = sin(t) + sin(3*t)/3 + sin(5*t)/5 + sin(7*t)/7 + sin(9"t)/9; 
»plot(t.y) 
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The resultant unenhanced MATLAB output is shown be- 
low. 
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Figure 2 - MATLAB Output For Gibb’s Effect 


Still not impressed? Suppose we wanted to evaluate the 
function 


over the range 
-2<х<2, -2<у<3 


АП we have to do is use the following 3 MATLAB state- 
ments to get a 3 dimensional plot (with all the hidden line 
algorithms transparent to the user) of the function. 


»[x,y]=meshdom(-2:.2:2,-2:.2:3); 


»ZzX." exp(-x.^2-y.^2); 
»mesh(z) 
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Figure 3 - MATLAB 3 Dimensional Plot 


Incidentally, the plot took only a few seconds to generate. 
Try doing that in FORTRAN! 


Signal Processing 
Noisy signals can be analyzed with MATLAB. For ex- 
ample, we can make 750 gaussian distributed random numbers 


with zero mean and unity standard deviation with the statements 


»rand(‘normal’) 
»y=rand(750,1); 
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Wecan then analyze and display the frequency contentof the 
750 random numbers with a MATLAB histogram statement or 


> [n,x]=hist(y); 
»plot(x,n, +) 


As expected, the MATLAB output, shown in Fig. 4, demon- 
strates that the 750 random numbers follow the standard “bell- 
shaped" curve or well known gaussian distribution. 
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Figure 4 - MATLAB Can Make Histograms 


As was mentioned in the introduction, MATLAB comes 
with very powerful algorithms. The next example shows a 
simple use of the FFT (Fast Fourier Transform) function. A 
common use of the FFT is to find the frequency components 
buried in a noisy time domain signal. Consider data sampled at 
1000 Hz. We сап form asignal containing 50 Hz and 120 Hz and 
corrupt it with gaussian noise (zero mean and unity standard 
deviation) with the following 5 MATLAB statements. 


»t=0:.001:.5; 
»X=Sin(2*pi*50"t)+sin(2*pi*120"t); 
»rand(‘normal’) 

»Y=X+2"rand(t); 

»plot(y(1:50)) 
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Figure 5 - Noisy Signal іп Time Domain 


It is difficult, if not impossible, to identify the frequency 
components by looking at the original signal in the time domain. 
Converting to the frequency domain, the discrete Fourier trans- 
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form of the noisy signal y is found by taking the FFT. In 
MATLAB code this means 


> Y afft(y); 


The power spectral density, a measurement of the energy at 
various frequencies, is: 


»PyyzY.*conj(Y); 


We can plot the power spectral density by forming a fre- 
quency axis for the first 256 points (the other 256 points are 
symmetric) with the MATLAB statements 


»f=1000*(0:255)/512; 
»plot(f, Pyy(1:256)) 


From the resultant output in Fig. 6 we can clearly see the 
frequency components at 50 Hz and 120 Hz of the signal. 
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Figure 6 - Frequency Domain Output 
Control Analysis 
MATLAB can also be usedin the analysis of control systems 


from both a modern and classical point of view. We can find and 
plot the root locus of the transfer function 


2 
2S +.3$+1 
Н (5) - 


ТҰТ Т 


for gains 0 to 10 in steps of .5 with the following MATLAB 
statements 


»num = [.2 .3 1]; 
»den1 = [1 .4 1]; 
»den2 = [1 .5]; 


»den = conv(dent,den2); 
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»К = 0:.5:10; 

»r = rlocus(num,den,k); 

»plot(r,’x’), title(‘Root-locus’),xlabel(‘Real 
part’), ylabel(‘Imag part’) 


The resultant root locus is shown in Fig. 7. 


Root-locus 


Real part 


Figure 7 - Root Locus Example With MATLAB 


We could find the step response for the same system by 
typing the additional statements 


»[a,b,c,d] = tf2ss(num,den) 

»t = 0:.3:15; 

»у = Step(a,b,c,d, 1,t); 

»plotit,y),title(‘Step response’),xlabel(‘time(sec)’) 


yielding the output of Fig. 8 


Step response 


0 5 10 15 
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Figure 8 - Step Response Output 


Anotherexample of the control system analysis capability of 
MATLAB consider a second order quadratic transfer function 
with natural frequency 1 rad/sec and damping of .2. The 
MATLAB program required to display the magnitude character- 
istics is shown below and the resultant output is displayed in Fig. 
9. 
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»[a,b,c,d]=ord2(1,.2); 
»w=logspace(-1,1); 

»[mag, phase]=bode(a,b,c,d,1,w); 
»mag 1=20*log10(mag); 
»semilogx(w,mag1) 


Figure 9 - Sample Magnitude Bode Plot For 
Quadratic Transfer Function 
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More Details 


If you already used MATLAB in the DOS world and have a 
collection of many files there is no problem in porting them to the 
MAC. Just use a file transfer program (I used PC to MAC and 
Back) and the conversion routine (going from ASCII files to .m 
files) provided by MATLAB. The danger in doing this is that the 
DOS version of MATLAB will seem very primitive once you 
have used the MAC version. Incidentally the MAC version of 
MATLAB runs about 5 times faster than the IBM/AT version and 
at about the same speed as the Sun-3 Workstation version. 


Macintosh MATLAB was developed by The Math Works, 
Inc. [20 М. Main St., Suite 250, Sherborn, Mass. 01770, 
(617)653-1415]. The software, including the signal processing 
toolbox comes on a single 800k disk (unprotected) with a list 
price of $895. The control and ientification toolboxes are sold 
separately - each with alistprice of $495. Although this software 
isexpensive by MAC word processing and spreadsheet standards 
- it is inexpensive by engineering software standards. = 


Сә 


«Қыс» 
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Fortran's World 


Fortran Printing Interface 


In Absoft FORTRAN version 2.3 one usually must 
employ Absoft's special routine called PrPort.sub in order to use 
the Printing Manager on the Macintosh. PrPort.sub employs the 
old RAM-based printing manager, but recent trends suggest that 
it would be better to use the printing traps accessible through 
“ PrGlue" at $A8FD since these routines are now in ROM and 
contain special routines such as PrGeneral that are unavailable in 
the RAM-based printing manager. In addition, PrPort.sub, which 
is written in assembly language, is limited to the hard-coded 
routines which existed at the time Absoft developed the routine 
and is thus not extendible. Since usage of PrPort.sub will un- 
doubtedly limit the development of FORTRAN programs on the 
Macintosh, it is of interest to see how one might use Absoft's 
Toolbx.sub in order to implement the new ROM-based printing 
manager traps. 

The Toolbx.sub routine from Absoft employs an en- 
coded ‘trap dispatch’ LongInt to describe the toolbox or OS trap 
number, as well as to describe the parameters required for the 
toolbox or OS calls. The new printing traps accessible through 
the PrGlue trap at $A8FD require that a special ‘routine selec- 
tor’ be pushed onto the stack prior to the $A8FD trap instruction. 
Hence, if we are to succeed in using the print traps, we must be 
able to insert this routine selector number onto the stack. 

By studying and disassembling Absoft’s Toolbx.sub it 
was found that the routine selector parameter could be put into the 
Toolbx.sub call as the final parameter (i.e. the parameter just 
before the final closing parenthesis) and that it would be pushed 
onto the stack just before Toolbx.sub executed the trap number. 
In order to instruct Toolbx.sub that there was another parameter 
for it to pass, however, the ‘trap dispatch’ code had to be 
modified. That is where the disassembly of Toolbx.sub became 
important because current Absoft documentation is not always 
correct on this matter. 

We have developed the include files ‘prtrap.inc’ and 
‘PrGenDefs.inc’ which can be used with Absoft Fortran's 
Toolbx.sub in order to implement the print traps. A similar 
method could be employed for any other new traps (or traps and 
additional routine selectors’) that Apple develops. The file 
‘prtrap.inc’ contains the encoded trap dispatch number and the 
routine selector for all the new print traps documented in Inside 
Macintosh Volume V. The routine selector for PrGeneral, which 
inadvertently was left out of Inside Mac, was found in Lightspeed 
Pascal’s equates as $70070480. We also include a file 
‘PrGenDefs.inc’ which contains the equates required for use of 
the PrGeneral gateway, potentially a very useful new trap which 
enables one to check and to set the resolution of the printer in use. 

To demonstrate how the Toolbx.sub traps are imple- 
mented in a program, first consider the Pascal calling-sequences 
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Jay Lieske 
La Canada, CA 
MacTutor Vol. 4 No. 8 


== 


fortran 


as documented in Inside Mac. Suppose that a trap ‘PrRoutine’ is 
documented by Apple as being implemented like this in Pascal: 
PrRoutine(Argl, Arg2,...,Argn); 
then the Toolbx.sub routine in Fortran would be employed as 
follows: 
call Toolbx( PrRoutineCode, Arg1, Arg2,...,Argn, xPrRouti- 

neCode) if the toolbox trap is a procedure. If the toolbox call is 
a function then the Pascal version would be 

Result := PrRoutine(Arg1, Arg2,..., Argn); 
while the Toolbx.sub Fortran version would be 

Result = Toolbx(PrRoutine,Arg1, Arg2,..., Argn,xPrRoutine). 
The analogous calls using prport.sub for a subroutine would be: 
call PrPort(Code, Argl, Arg2,..., Argn). Programs which cur- 
rently employ PrPort could readily be changed simply by replac- 
ing PrPort with Toolbx and appending the ‘xPrRoutine’ parame- 
ter. 


An example program ‘demotrap.for’ is included for 
implementing the new print manager trap-based calls. The 
program does not actually do any printing, but shows how one 
can access the print record and query the printer for variable 
resolutions. Just use the Chooser to select your ‘printer’ and then 
the usual dialogs will come up on screen to demonstrate that 
everything works as advertised. A colleague has employed these 
new traps in a large plotting package which was ported over to the 
Mac from a mainframe computer and the results are quite 
satisfactory. 


Listing One: Demonstration Program 
program demotrap 

б See if can use ‘Printer traps’ via $A8FD PrGlue and 
TOOLBX . sub 

С А simple sample program demonstrating its capability 
for Absoft Fortran 2.3. 

C This program does not actually do any printing. 

С J. Lieske 12/87 


СХхххххххххж 


* FUNCTION PTR CANYTYPE) : PTR; 
trap. 


; А ‘funny’ 


INTEGER PTR 
Absoft’s MISC. inc 
PARAMETER CPTRzZ'C0000090 ' ) 


! from 


integer NEWHANDLE 

! from Absoft’s MEMORY. inc 
parameter CNEWHANDLE=Z’ 12200048 ' ) 
integer iPrintSize 

! The Print record ѕіге. (120 bytes] 
parameter CiPrintSizez 120) 

! from Absoft’s PRDEFS. inc 
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C * X X X ttt ttt * 
С  GRXMXØ : default x size (pixels). These will be taken 
from the print record 
C  GRYMXO : default y size (pixels) 
C  GRXPIN : pixels per inch in x 
C  GRYPIN : pixels per inch in y 
REAL GRXPIN, GRYPIN 
INTEGER СЕХМХО, GRYMXO 
INTEGER*4 TOOLBX 
! MAC TOOLBOX INTERFACE 


х integer*4 debugger 

| just in case you want to use MacsBug 
X parameter Cdebugger-z 9FF090000 ' ) 
X call toolbx(debugger ) 

! put the call where it’s needed 

x 


* INITIALIZE THE PRINT RECORD FOR THE MACINTOSH 
x 


integer*2 iversion 
integer*2 ernum 


* PRINT MANAGER FUNCTION DEFINITIONS for toolbox-based 
treps 
include prtrep.inc 
include PrGenDefs.inc 


INTEGER PRRECHDL 

! HANDLE TO THE PRINT RECORD. 
INTEGER POINT 

! DEREFERENCED HANDLE 
LOGICAL OK 


write(*,*) ‘This program demonstrates printer traps 
in Fortran.’ 

writeC*,*) ‘It won’’t actually print anything, but 
shows how to’ 


writeC*,*) ‘access the printer traps іп Absoft 
Fortran. ’ 

write(*,*) ‘It will write the data out to 
‘output. РТ?” 

writeC*,*) ‘so you can read it.’ 


call toolbx(propen, xpropen) ! Рг0реп 


PRRECHDL = TOOLBXCNEWHANDLE, IPRINTSIZE) ! GET А 
PRINT RECORD HANDLE. 

call toolbx(printdefault,PRRECHDL , xpr intdef aul t) 
! get defaults 


C get printer version number 
iversion - toolbx(prdrvrvers, xprdrvrvers ) 
write (*,*) 'iversion = ”, iversion 
open( 15,file=’output.fil’, status=’NEW’) 
write (15,4) ‘iversion = “, iversion 


C see if PrGeneral will work 
gOpCode = 4 | set 10рСоде 
C-use PTR to get address of data record 
pGetRslData = toolbx(PTR, GetRs1DataRec) 
call toolbx(PrGeneral, pGetRsIData, xPrGeneral 2 
C should now check for PrError also 
ernum = toolbx(PrError, хРгЕггог 2 
writeC*,*) 'PrError number = ', ernum 
writeC15,*) 'PrError number = ', ernum 


write(*,*) ‘Interpreted record’ 
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write(*,*) ‘i0pCode= ',gO0pCode 

write(*,*) ‘iError= ',gError 

writeC*,*) 'lReserved- ',gReserved 

writeC*,*) 'iRgTgpes ',iRgType 

write(*,*) 'XRslRg- ',XRs!Rg 

write(*,*) 'YRslRg- ‘,YRSIRg 

writeC*,*) “iRslRecCnt= ',iRslRecCnt 

writeC*,*) 'rgRslRec- ',CCrgRsIRecCi, j), 1=1,2), 
j=1, iRslRecCnt? 


writeC15,*) ‘Interpreted record’ 

writeC15,*) *і0рСоде= ”,90рСоде 

writeC15,*) ‘iError= ',gError 

writeC15,*) 'lReserved- ',gReserved 

writeC15,*) ‘iRgType= ',iRgType 

write(15,*) ‘XRsIRg= ',XRsIRg 

writeC15,*) ‘YRsIRg= ',YRsIRg 

writeC15,*) 'iRslRecCnts ',iRslRecCnt 

writeC15,*) 'rgRslRec- ',CK(rgRslRecCi,j2, i=1,2), 
j=1, iRslRecCnt) 


C now try to set it to 300 dpi 


pOpCode - 5 ! set 10рСоде for SetRs] 
hPrint - PRRECHDL ! handle to print record 
iXRs! - 300 
1ҮК61 = 300 


pSetRs] = toolbxCPTR, SetRslRec) 
call toolbx(PrGeneral, pSetRs!, xPrGeneral) 


ОК = toolbx(prstldialog,PRRECHDL,xprstldialog) | 
std dialog 


OK-toolbxCpr jobdialog,PRRECHDL, xpr jobdialog) ! 
PrJobDialog 
if C.not. OK) STOP 
x NOW READ PLOT DIMENSION VALUES WITH THOSE FROM THE 
PRINTER INFO RECORD. 


* PRRECHOL IS A HANDLE TO THE PRINTER RECORD WHICH IS 
120 BYTES 


* THE VALUES WE CARE ABOUT ARE THE VERTICAL AND 
HORIZONTAL RESOLUTION 


* AND THE PAGE RECTANGLE WHICH ARE AT OFFSETS 4,6, AND 
8 INTO THE RECORD 


POINT=LONG(PRRECHDL) 


GRXMX@ = WORDCPOINT* 14) 
GRYMXØ = WORDCPOINT+ 12) 
GRXPIN = FLOATCWORDCPOINT*62) 
GRYPIN = FLOATCWORDCPOINT+4)) 


write(*,*) ‘resolutions’, 
СЕХМХО, GRYMXØ , GRXPIN, GRYP IN 

writeC 15, *) 
‘resolutions’ ,GRXMX9, GRYMX®, GRXPIN, GRYPIN 

close( 15) 


ы CLOSE UP THE PRINTER 
x 


call toolbxCprclose,xprclose) ! Close the 


printing grafport 
peuse 'Press return to exit" 


stop 
end 
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Listing Two: РгТгар. іпс 


* File: ргігар. іпс 29 Dec 1987 JHL 
x А replacement for Absoft’s prport.inc and prport.sub 
x This implements traps for Fortran so that it can be 


used with toolbx.sub . 

t Called together by J. Lieske, Jet Propulsion 
Laboratory, based upon 

x Inside Mac V and Lightspeed Pascal equates. 


The general calling sequence Гог procedures is 
CALL TOOLBX(PrRoutine, Args, xPrRoutine) 
while that for a function is 
TOOLBX(PrRoutine, Args, xPrRoutine) . 
In the above parameters, PrRoutine is the encoded 
lue (Printer Trap 
#A8FD) parameter and xPrRoutine is the “call number’ 
as specified in 
* Inside Mac V Chapter 22. Тһе 'Args' are the 
sequence of arguments to 


Pr 


* OQ м хм ы м 5 


x the procedure or function as specified by Inside 
Mac. 
* Basically, the xPrRoutine “call number’ is 


placed on the stack 
x just ahead of the printer trap number ($A8FD) and 
the Fortran PrRoutine 


* рагате{ег tells Ғогігап”5 TOOLBX how to interpret 
the 'Args' and 

x ‘xPrRoutine’ values. 

* Рог example, the routine PrintDefault is 


called from 

x Fortran as follows: CALL TOOLBXC PRINTDEFAULT, 
hPrint, xPRINTDEFAULT) . 

x 


X X X X X X X X X X X X X X X X X X * x x 
Ж Modification history: 
x 12/87 JHL Developed basic parameters from Absoft’s 
documentation 
х of toolbx.sub and Apple's Inside Mac V 
and Lightspeed 
x Pascal. 
X X X X X X X X X X X X X X X X X X X OK x 
ж PROCEDURE PrOpen; 
INTEGER*4 PROPEN, xPROPEN 
PARAMETER CPROPEN-Z '8FD 10000", xPROPEN-Z'C8000000 ' ) 


х PROCEDURE PrClose; 
INTEGER*4 PRCLOSE, xPRCLOSE 
PARAMETER (РЕСІ 05Е-7”8Ғ010000", 
xPRCLOSE=Z ^D0900900 ' ) 


* PROCEDURE PrintDefault ChPrint: THPrint); 
INTEGER*4 PRINTDEFAULT, xPRINTDEFAULT 
PARAMETER CPRINTDEFAULT-Z /8FD 12000 ' , 

XxPRINTDEFAULT=Z ^20040480' ) 


х FUNCTION PrValidate ChPrint: THPrint) : BOOLEAN; 
INTEGER*4 PRVALIDATE, xPRVALIDATE 
PARAMETER CPRVALIDATE-Z'8FDD2900 ' , 
xPRVAL IDATE=Z 52040498 ' ) 


х FUNCTION PrStiDialog C(hPrint: THPrint) : BOOLEAN; 
INTEGER*4 PRSTLDIALOG, xPRSTLDIALOG 
PARAMETER CPRSTLDIALOG-Z ^8FDD29000 ' , 

XPRSTLDIAL0G-7^2A040484' ) 
х FUNCTION PrJobDialog C(hPrint: THPrint) : BOOLEAN; 


O The Definitive MacTutor, Vol. 4 


INTEGER*4 PRJOBDIALOG, xPRJOBDIALOG 
PARAMETER CPRJOBDIALOG-Z '8FDD2000 ' , 
xPRJOBD I ALOG=Z 32040488 ' ) 


х PROCEDURE PrJobMerge ChPrintSrc, hPrintDst: THPrint); 
INTEGER*4 PRJOBMERGE, xPRJOBMERGE 
PARAMETER CPRJOBMERGE=Z ’8FD 12400 ' , 
хРЕЈОВМЕВСЕ=2 ^5804989C ' ) 


* FUNCTION PrOpenDoc ChPrint: THPrint; pPrPort: TPPrPort; 
x pIOBuf: Ptr) : TpPrPort ; 
INTEGER*4 PROPENDOC, xPROPENDOC 
PARAMETER CPROPENDOC-Z ’8FD92489' , 
xPROPENDOC=Z ”04000С00"2 


х PROCEDURE PrCloseDoc (pPrPort: TPPrPort) ; 
INTEGER*4 PRCLOSEDOC, xPRCLOSEDOC 
PARAMETER CPRCLOSEDOC-Z ^8FD 12000 ' , 

xPRCLOSEDOC=Z “08000484 ' ) 


х PROCEDURE PrOpenPage (pPrPort: TPPrPort; pPageFrame: 
TPRect); 
INTEGER PROPENPAGE, xPROPENPAGE 
PARAMETER CPROPENPAGE=Z ’8FD 12400 ' , 
xPROPENPAGE=Z ’ 10000808 ' ) 


х PROCEDURE PrClosePage (pPrPort: TPPrPort); 
INTEGER*4 PRCLOSEPAGE, xPRCLOSEPAGE 
PARAMETER CPRCLOSEPAGE-Z ^BFD 12090 ' , 

xPRCLOSEPAGE 22  1800040C ’) 


* Note: prStatus should actually be passed as a pointer to 
a TPrStatus 
* record. 
* PROCEDURE PrPicFile ChPrint: THPrint; pPrPort: TPPrPort; 
pIOBuf: Ptr; 
* pDevBuf: Ptr; VAR prStatus: TPrStatus); 
INTEGER*4 PRPICFILE, xPRPICFILE 
PARAMETER (PRPICFILE=Z’8FD 124B82' , 
xPRPICF ILE2Z ^6005 1480 ' ) 


* FUNCTION PrError : INTEGER; 
INTEGER*4 PRERROR, xPRERROR 
PARAMETER CPRERROR-Z ^8FD50000 ' , 

XPRERROR-Z ^BA200000 ' ) 


х PROCEDURE PrSetErrorCiErr : INTEGER); 
INTEGER*4 PRSETERROR, xPRSETERROR 
PARAMETER CPRSETERROR-Z '8FDOA200 ' , 

xPRSETERROR-Z ^C0000200 ' ) 


х PROCEDURE PrDrvrOpen; 
INTEGER*4 PRDRVROPEN, xPRDRVROPEN 
PARAMETER CPRDRVROPEN-Z ^8FD 10000 ' , 

xPRDRVROPEN=Z ^80000000 ' ) 


* PROCEDURE PrDrvrClose; 
INTEGER*4 PRDRVRCLOSE, xPRDRVRCLOSE 
PARAMETER CPRDRVRCLOSE-Z ’8FD 10000 ' , 

ХРКОКҮКСІ 05Е-7”88000000 ' ) 


х PROCEDURE PrCtlCallCiWhichCtl: Integer; 1Param1, 
lperam2, lparem3: LongInt); 
INTEGER*4 PRCTLCALL, xPRCTLCALL 
PARAMETER CPRCTLCALL=Z ^8FD2A490 ' , 
xPRCTLCALL=Z " A9000E 00 ' ) 
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х FUNCTION PrDrvrDCE: Handle; 
INTEGER*4 PRDRVRDCE, xPRDRVRDCE 
PARAMETER (РЕОКҮКОСЕ-27”8Ғ090000", 
xPRDRVRDCE-Z ^94000000 ' ) 


* FUNCTION PrDrvrVers: Integer; 
INTEGER*4 PRDRVRVERS, xPRDRVRVERS 
PARAMETER CPRDRVRVERS=Z ^8FD59000 ' , 

xPRDRVRVERS=Z ”94000000" ) 


ж PROCEDURE PrGeneralCpDaeta: Ptr); 
INTEGER*4 PRGENERAL, xPRGENERAL 
PARAMETER CPRGENERAL=Z ’8FD 12000 ' , 
xPRGENERAL=Z ^70070480 ' ) 
х PrGeneral is the gateway to the calls documented in 
Inside Mac V 
* concerning added capabilities for printer resolution, 
etc. 
X Зее the file PrGenDefs.inc and the demo ргодгат for 
usage 


ж PROCEDURE PrPurge; 
INTEGER*4 PRPURGE, xPRPURGE 
PARAMETER CPRPURGE=Z ’8FD 19000 ' , 
xPRPURGE=Z ”А8000000"2 


* PROCEDURE PrNoPurge; 
INTEGER*4 PRNOPURGE, xPRNOPURGE 
PARAMETER CPRNOPURGE=Z ^8FD 10900 ' , 
xPRNOPURGE=Z ^B0000000 ' ) 


х FUNCTION PrStlInit ChPrint: THPrint): ТРРг019; 
INTEGER*4 PRSTLINIT, xPRSTLINIT 
PARAMETER CPRSTLINIT2Z'8FD92000 ' , 
xPRSTLINIT2Z'3C04040C ) 


х FUNCTION PrJobInit ChPrint: THPrint): ТРРг019; 
INTEGER*4 PRJOBINIT, xPRJOBINIT 
PARAMETER CPRJOBINIT-Z^/8FD92900 ', 
ХРКУОВІМІТ-77”44040410”2 


х FUNCTION PrDigMainChPrint: THPrint; pDlgInit: ProcPtr): 


Boolean; 
INTEGER*4 PRDLGMAIN, xPRDLGMAIN 
PARAMETER CPRDLGMAIN=Z ^BFDD2490 ' , 
xPRDLGMAIN=Z ”4Ү4040894" 2 


* end of prtrep.inc listing 


Listing Three: PrGenDefs.inc 

* File: PrGenDefs.inc Definitions for calls to printer 
trep PrGeneral 
ж 1/11/88 Jay Lieske 

x 

ж Information for GetRs] 

x This file contains definitions for calls to PrGen- 
eral with 10рСоде=4 


x (called gOpCode here) which is the GetRslData call. 


x 


ж the GetRslData record is of length 128 bytes 
integer*1 — GetRslDetaRec( 128) 


integer*2  gOpCode 
integer*2  gError 
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integer*4 gReserved 
integer*2 . iRgType 
integer*2 . XRsIRg(2) 
integer*2 — YRsIRgC2) 
integer*2 — iRslRecCnt 
integer*2 — rgRslRec(2,27) 
! defined as ARRAY[1..27] of 


TRslRec 


equivalence CGetRslDaeteRecC1), gOpCode) 
equivalence CGetRslDateRec(3), gError) 
equivalence CGetRslDateRec(52, gReserved) 
equivalence (GetRslDataRec(9), iRgTupe) 
equivalence (GetRslDataRec(11), XRsIRg) 
equivalence CGetRslDataeRecC15), YRsIRg) 
equivalence CGetRslDataRecC19), iRslRecCnt) 
equivalence CGetRslDataRec(210, rgRslRec) 


integer*4 pGetRs1Data 
C peremeter CgOpCode - 4) 


х You must set the value of gOpCode 
Ж in program. Get pointer to GetRslDateRec via: 


pGetRs1Data = TOOLBXCPTR,GetRsTDateRec ) 


* and then CALL toolbxCPrGeneral, pGetRslData, xPrGeneral) 
* end of data for GetRs] 


х Information for SetRs] 
x This file contains definitions for calls to PrGen- 


eral with 10рСоде=5 


x (called pOpCode here) which is the SetRslData call. 
x 


* the SetRslData record is of length 16 bytes 


integer*1 — SetRslRecC 16) 
integer*2 р0рСоде 
integer*2 рЕггог 
integer*4 рВеѕегуед 
integer*4 РРгіпі 
integer*2 — 1ХЁ51 
integer*2 iYRs] 


equivalence (SetRslRecC1), pOpCode) 
equivalence (SetRslRec(3), pError) 
equivalence C(SetRslRec(5), pReserved) 
equivalence (SetRslRec(9), hPrint) 
equivalence (SetRslRecC 13), iXRs1) 
equivalence (SetRslRecC 15), iYRs1) 


integer*4 pSetRs] 
C parameter CpOpCode = 5) 


х You must set the values of pOpCode = 5 and hPrint = 


hendle to Print Record 


Ж in program. Get pointer to SetRslRec via: pSetRs! = 


TOOLBXCPTR, SetRs Rec? 


* and then CALL toolbx(PrGeneral, pSetRs], xPrGeneral) 
х end of data forSetRs] 


* end of file PrGenDefs. inc 
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Chuck Bouldin 
Washington, DC 


Fortran's World 


fortran 


The Status of Fortran 


Status of Fortran on the Macintosh 


Until recently there has been a noticeable shortage of Fortran 
compilers for the Macintosh (translation: there has only been one 
Fortran compiler). This situation has changed enough that it is 
worthwhile to look over the available compilers and see what 
each has to offer. With the advent of the Mac II and Apple’s new 
emphasis on “Desktop Engineering” there is now enough interest 
and cpu horsepower to transform the Mac into a serious “plat- 
form” for scientific and engineering applications. Finally, the 
Mac П is being treated by Apple and others as a serious low-cost 
alternative to more expensive workstations, so the availability of 
industrial strength Fortran compilers is an obvious requirement. 


What’s Available 

At this writing, there are three Macintosh Fortran compiler 
vendors; Absoft, with a 68000 Fortran for the Mac+ and SE and 
a 68020 version for the Mac II and Mac’s with accelerator cards. 
DCM has a Fortran with both 68000 and 68020 code generation, 
so it is suitable for both Mac+ and SE, as well as ће Mac II. А 
third vendor, Language Systems, has just released a Fortran 
compiler that runs under MPW. Absoft is also in beta-test with 
a new Fortran ( Risc Architecture Technology, or “R AT”) that 
runs under Apple Unix and with MPW. The RAT compiler 
augments, but does not replace the existing MacFortran com- 
piler, as it requires a 68020 and 68881. All of this products 
include inline hardware floating point code generation, a crucial 
factor for fast floating point calculations. 


A Variety of Approaches 

The compilers available (or soon available) for the Mac 
show a variety of different approaches to providing an “environ- 
ment” for Fortran on the Mac. Each approach carries with it some 
inherent strengths and weaknesses. I want to go over these 
carefully before getting into comparisons of code size, execution 
speed, etc, since itis these differences in approach, not things like 
compile speed or code size that are frequently the limitation in the 
overall productivity of a programmer. There are inevitably 
subjective decisions in comparing these approaches, and I will 
make some. However, I will also try to be clear about why I make 
those decisions so that you can decide which of these products is 
most suited to your needs. 


DCM Fortran 
This is the only true “integrated” environment in the bunch. 
With this product you have an environmentin which you can edit, 
compile, link, symbolically debug and run programs. The editor 
is about on a par with the MDS “Edit”, but isn’t nearly as high 
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powered as, for example, Qued/M. The environment can be run 
under Multi-Finder, so if you want to use tools such as other 
editors or text utilities you can make them work reasonably well 
with this compiler. As with Absoft Fortran, this compiler allows 
both code and data to be larger than 32K in size. There are a 
number of extensions to ANSI Fortran, mostly improved flow 
control with SELECT CASE and other constructs. 

The classic dilemma of an integrated environment is that if 
you don’t like the setup as the vendor provides it, then itis usually 
difficult to modify. I find this environment marginally accept- 
able, as the editor seems under-powered compared to stand-alone 
alternatives and there are also minor problems with the Mac 
interface. For example, during compiles the cursor is not consis- 
tently maintained with the watch icon, so the user has no visual 
feedback that anything is happening. Worse, the edit windows do 
not have zoom boxes. Finally, this compiler has the ultimate 
“dumb” linker. A link simply appends the 155K runtime package 
to your compiled code. So the minimum size for any program is 
about 156K! You don’t have to link in the runtime library, as it 
can be auto-linked at execution, but the size of this runtime 
package will be a real detriment to anyone seeking to write 
applications to distribute. 


Absoft MacFortran 

This compiler is now in beta-test in the 2.4 version. This is 
much improved over the 2.3 release, with a number of bug fixes 
and a much better Mac interface. The compiler can now be 
configured so that your choice of text editor, as well as the Fortran 
linker, Debugger, Scriptbuilder, etc, can be “sub-launched” from 
the compiler. This does a lot to speed up transfers between the 
pieces of the programming environment, and also allows the 
programmer flexibility in choosing those pieces, such as speci- 
fying your favorite text editor. A script-builder utility similar to 
the MPW Commando is now provided to tame the atrocious 
command line interface which was the only way to run the Linker 
in the 2.3 version. In addition, Scriptbuilder can be used to 
construct a list of files for doing multiple compilations without 
operator intervention. The runtime library and user pre-compiled 
subroutines can be automatically linked at execution, so during 
development it is almost never necessary to use the linker. As 
with DCM Fortran, linking the runtime library to your code just 
copies in the entire library, but in this case you only have to carry 
around 12K for the runtiine package. There are extensions to 
ANSI Fortran that are similar to those in DCM Fortran. Also in 
common with DCM, Absoft Fortran has no restrictions on code 
or data sizes, other than available memory. 

This compiler has developed a bad reputation for bugginess. 
The 2.4 beta release fixes a number of these, and Absoft has taken 
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steps to improve feedback from users by establishing a dial-in 
bulletin board that users can access to obtain information, fixes 
and to report bugs. Along with the clean up of bugs and improve- 
ment in the Mac interface in the 2.4 version, this compiler appears 
to be much improved. The compiler does not correctly support 
the Fortran ENTRY statement, but as far as I know, this is the 
only deviation from the ANSI standard for Fortran. 


Language Systems Fortran 

This is a Fortran that runs under MPW. This brings with it all 
the power and tools of MPW, such as cross-linking with C and 
Pascal, support for MacApp and (Someday! Are you listening, 
Apple?) the common symbolic debugger that will work with all 
these tools. This is definitely a power environment for serious 
Fortran development work, but it also implies that you carry 
around the baggage of MPW whether you want it or not. In 
practice, you actually need to learn very little about MPW to get 
started. Once script files to compile and link your programs are 
developed, the MPW environment for Fortran is reasonably 
*Mac-like". There is a Commando interface for the compiler, so 
it is easy to get started. Language systems also provides calls to 
Mac Toolbox routines as inline constructs rather than through a 
“pointer” subroutine, as in DCM and Absoft Fortran. Finally, this 
is the only compiler that supports Structures and Records, so that 
complicated data constructs are handled by the compiler, rather 
than arduously mapped onto arrays by the programmer. This is 
an important consideration for accessing the Mac Toolbox since 
this always requires data structures, some of which are complex. 
This compiler supports 68020 and 68881 code generation. Be- 
cause of Apple's decisions the MPW compiler is stuck with the 
32K segment limit on code, although they allow data to exceed 
32K in size. 


Absoft RAT Compiler 

This is a new Fortran that runs under MPW. The interesting 
thing about this compiler, which is still in early beta testing, is that 
the compiler does some optimizations that are usually associated 
with RISC (reduced instruction set chip) microprocessors. The 
compiler requires both a 68020 and 68881. The compiler treats 
the register pool of both processors as one set of registers, and the 
contents of these registers are allocated dynamically witha score- 
boarding technique. What this means is best illustrated by an 
example. A compiler will ordinarily choose, automatically or 
under programmer control (as with the Register keyword in C), 
certain variables that are kept in cpu registers. This optimization 
is done on a module-wide basis. That is, registers allocations are 
constant over the execution of a subroutine. This is fine until you 
run out of registers. For example, if a compiler has three registers 
left to allocate when it compiles a code structure of three nested 
DO loops, then the loop counters may be put into registers. 
However, if the compiler now encounters another set of triply- 
nested DO loops farther along in the same subroutine, itis usually 
impossible for those counter variables to go into registers. The 
departure that the RAT compiler takes is that registers contents 
are optimized ona line-by-line rather than subroutine-wide basis. 
In the above example, the first three loop counter variables could 
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go into registers and then be flushed out and replaced with the 
next set of three loop counters. This register score-boarding 
method should help most in code that is large and complicated, 
with lots of variables, which where a traditional compiler willrun 
out of registers variables to statically allocate. 

As in Language Systems Fortran there is a Commando 
interface for the compiler and calls to Mac Toolbox routines are 
inline calls. However, there are no Structure or Record data types, 
50 one must still use array declarations and equivalence state- 
ments to pass arguments to Toolbox routines. Also, the RAT 
compiler will not be available until Apple releases MPW 3.0, as 
Absoft is waiting for Apple to provide a fix for the 32K data 
segment limit, rather than coding around Apple's mistake as 
Language Systems was forced into. 


Benchmarks 

With Fortran, there are a number of quasi-standard bench- 
marks that have been run on almost all machines. These are not 
Mac specific, so they do not test the ability of the compilers to 
provide support for the Macintosh environment, but they do have 
the advantage that they have been run on many other machines, 
allowing broader comparisons to be made. I chose to evaluate 
these compilers with the three most common tests: the Sieve of 
Eratosthenes, the “Whetstone”, and the double-precision Lin- 
pack. These tests emphasize, respectively, integer operations and 
addressing of small arrays (Sieve), floating point operations and 
transcendental function evaluation (Whetstone) and solution of 
linear equations, double-precision floating point arithmetic and 
addressing of large arrays (Linpack). In addition I kept track of 
compile times and code sizes of these three programs. 

АП compilers were run with options set to maximize com- 
pile and execution speed. All compilations were done with IN- 
ТЕСЕК*4 as the default storage class, and I took no pains to 
tweak options to change code size. All tests were run on a Мас“ 
with a Novy systems 16 mhz 68020/68881 upgrade board with 4 
megs of 1 wait-state memory, a 512K disc cache and a MacBot- 
tom 45 hard disc with 26 msec seek time. In computation speed, 
this system is roughly the same speed as a Mac II. The results are 
tabulated below. Each position in the table contains, from top to 
bottom, the results for DCM Fortran 3.0 , Absoft MacFortran 2.4 
‚ Language Systems Fortran 1.1, and Absoft RAT Fortran “рге- 
beta". АП sizes are in kilo-bytes and all execution times, except 
Whetstone, are in seconds. Whetstone results are traditionally 
reported in units of ““whetstones per second”. For this benchmark 
only, alarger number means faster execution. Finally, for Whet- 
stone and Linpack, I included speeds for a VAX 11/780, so you 
can see how well this desktop computer is doing against a large 
mainframe! 


Results of Generic Fortran Tests 
These test results need to be interpreted with some care. For 
example, an important distinction in the Compile and Link time 
results is that DCM Fortran and MacFortran do an automatic 
link-at-runtime, which is the time reported in the table, while 
RAT and Lang. Sys. both use the MPW linker, so they always 
require an explicit hard link. This is one example of the compro- 
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mises that one makes by running under MPW rather than your 
own integrated environment. 

On compile speed, it is a race between DCM and MacFor- 
tran. DCM is the fastest turnaround for very small code, but 
MacFortran starts to edge it out as code size grows. The RAT 
compiler is competitive on compile speed, but both it and Lang. 
Sys. suffer from link times under MPW. 

The Absoft RAT compiler sweeps the field on execution 
speed, a reflection of the superior optimization features of this 
compiler. As predicted, the register scoreboarding technique has 
little effect on Sieve, where there are so few variables that static 
register allocation is virtually as good as dynamic optimization. 
On Linpack and Whetstone, the optimization in RAT makes a 
marked difference. Averaged over the three tests the other 
compilers are comparable in execution speed. 

Code size is a complicated issue, as this is where differences 
in "philosophy" will show up most glaringly. MacFortran and 
RAT are the winners for small code size, partly because of the 
small runtime libraries. This is a minimalistapproach, trading off 
small code size for little built in Mac support. For example, in 
MacFortran the runtime library only supports a non-scrollable, 
non-resizable “glass ТТУ” window and no support for desk 
accessories or other parts of the Mac environment. Language 
Systems and DCM provide more built in Mac features, which 
accounts for some of the code size. The Language Systems 
runtime support includes a scrollable text edit window with the 
usual File, Edit and Apple menus. If you want a reasonable built- 
in Mac interface, this looks to be a reasonable compromise. 


Mac Programming Support 
The test that I ran are generic Fortran code, so how do we 
evaluate the Fortran compilers on their ability to generate real 
Mac-style applications? Generally speaking, it is very difficult, 
and often inappropriate, to attempt a full-blown Mac interface in 


Sieve Compiler and Link 


Linked Code Size 


Sieve 5.2 sec (DCM) 
9.5 sec (MacFor tran) 
29.0sec (Lang. Sys.) 
8.6 sec (КАТ) 


155 Kbyte 
13 Kbyte 
53 Kbyte 
20 Kbyte 


11.5 sec (DCM) 
11.6 sec (MacFortran) 
40.2 sec (Lang. Sys.) 
23.8 sec CRAT) 

1054К whets (УАХ) 


Linpack 14.5 sec (DCM) 
13.2secs (МасГог{гап) 
52.8 sec (Lang. Sus.) 
26.0 sec (RAT) 


171 Kbyte 
19 Kbyte 
59 Kbyte 
24 Kbyte 
4.9 secs (VAX) 


Figure 1. Test Results 


O The Definitive MacTutor, Vol. 4 


Execution Time 


Fortran. The main difficulty is that all the toolbox routines expect 
Pascal or C type data structures, which are not supported in most 
Fortran compilers and are not part of the ANSI 77 standard for 
Fortran (although they are in the proposed 88 standard). Tools for 
adding a Mac interface are therefore an important consideration 
in choosing a Fortran compiler. 

Fortran programmers have two main choices: (1) Use a 
Fortran that runs under MPW and program the interface code in 
Cor Pascal, or with MacApp and link to your Fortran code, or (2) 
Use a programming aid called Facelt. Facelt is a set of stand- 
alone code resources that can be easily added to your Fortran 
code and makes it trivial to add Macintosh look and feel to your 
programs. Facelt is presently available for MacFortran, and 
Language Systems Fortran, and should be available with RAT. 


Conclusions 

But first, a disclaimer. I have used the Absoft MacFortran for 
over 3 years, so Гат very familiar with that product. In contrast, 
Ihave used an evaluation copy of DCM Fortran for a few weeks, 
have used the Language systems Fortran for about a month, and 
used RAT just enough to get the 3 benchmark programs run. I 
have tried to be objective, but itis almost inevitable for two thin gs 
to happen: (1) I may tend to prefer MacFortran simply through 
familiarity. (2) Iam much more familiar with bugs and flaws in 
MacFortran because of more accumulated usage with it. 

With that settled, these are my conclusions. On a “‘by-the- 
numbers” basis, MacFortran and RAT are clear winners in the 
categories of stand-alone and MPW compilers. However, there 
is a lot more to overall productivity than the numbers in the table. 
Since I was trying to measure raw performance, the tests that I 
used are all “vanilla” Fortran and do not include any Mac features 
at all. In terms of runtime support of the Mac, MacFortran runs 
last, behind DCM and Language systems. If you want any Mac 
features, such as scrolling windows, DA support, etc, in MacFor- 


tran you do it all yourself. DCM and Lan- 
guage Systems are putting more code into 
the runtime package (hence the larger code 


12.1 secs 
9.8 secs 
13.5 secs 

9.1 secs 


160 Kbyte 632K whets 
16 Kbyte 545К whets 
55 Kbyte 540K whets 
22 Kbyte 838K whets 


sizes) to support the Mac environment. For 
applications that have a Fortran written Mac 
interface, the code sizes would probably be 
Closer than the examples that I chose. 
However, as I indicated above, my ap- 
proach is to avoid doing a Mac interface 
program in Fortran, and, instead, to use 
other tools which are better suited for that 
purpose. 

The choice of stand-alone compiler, 
integrated environment or MPW also has 
important consequences. For instance, I 
found all of the compilers to be very respon- 
sive in terms of compile speed and context 
Switching between programming tools. But, 
I am running on virtually the fastest Mac 
hardware available. On a floppy-based 
Мас+, the integrated environment of DCM 
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could be much more important. In the other direction, running 
under MPW confers the benefits of use of Mac-App or cross- 
linking with C or Pascal. This is not an unmixed blessing, 
however, as it ties the fortunes of the compiler to decisions made 
by Apple. For example, the 32K segment limit for data has not yet 
been eliminated and there is still no symbolic debugger for 
compilers running under MPW. 

The bottom line is that you must choose amongst these 
products on the basis of your needs. On systems that cannot 
support the overhead of MPW, or if just don't like MPW, you 
may well be happier with MacFortran or DCM. If you have an 
existing Mac interface in C or a commitment to MPW, then 


Language Systems offers a means to integrate mainframe Fortran 
code into a Mac interface shell, with lots of MPW tools to help 
you. 

I suspect that Fortran on the Mac is now going to see some 
of the improvements that we saw take place with C compilers 
once a competitive marketplace was established. We may even 
see programmers using a synergistic approach with several 
different Fortran compilers, just as some developers presently 
use Lightspeed C and MPW C at different times for different 


purposes. 


57 
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Lisp Listener 
MacScheme vs Coral Lisp 


Paul Snively is one of our favorite people; a long time 
МасТшог fan, and contributor, we are glad to have this contri- 
bution from him. Here are some notes Paul sent that will bring 
all his fans up to date on what he has been doing. 


Letter to MacTutor 


*Well, here it is—after a period of time that was entirely too 
long on two counts (too long both in terms of time between 
payment and delivery (roughly nine months) and time between 
receipt of software to support this article and delivery (about four 
months)). Good grief; look at those parenthesis—you can tell 
I've been working in Lisp lately! 

Let me congratulate you on the apparent ongoing success of 
MacTutor as an organization, and upon the consistently high 
overall quality of the content (my own work notwithstanding). 
The article on the writing of custom printer drivers was particu- 
larly welcome, and there is much more than could be done there. 
In particular, a LaserWriter driver that doesn't require the "Laser 
Prep" file (i.e. one that generates pure PostScript without any 
Apple-proprietary PostScript macros) would be a most welcome 
project from a number of standpoints, I think. 

Incase you might be curious as to what I’ve been up to lately, 
ICOM Simulations, Inc. has kept me pretty busy from day one, 
although the situation seems to be intensifying lately. Early on 
іп my time with ICOM, there was “ГМОМ Plus/TMON Profes- 
sional" (depending upon whom you talked to) to work on. 
Unfortunately that project met an early demise when it became 
clear that Waldemar would not be able to complete the kernel 
before he had to return to MIT after the summer. 

After that we concentrated on TMON 2.8, which was re- 
leased at Boston. Unfortunately, itisn’t everything that we might 
wish that it was (in particular, the lack of disassembly of '020 and 
'881 opcodes is hurting us, as is the funny-looking display when 
you're on a Mac II in multiple bit-planes). However, our 
customers seem happy to have something that at least will run on 
amachine with an '020, and it does have a few additional nicities 
(such as the INIT loader, the Programmer's Key INIT, better 
documentation, no VBL tasks while in TMON, etc.) 

Lately, and in some ways concurrently with all of this, we 
continue to write MacVentures. There's a certain irony in being 
the developers of the de facto standard Macintosh debugger and 
also of a series of adventure games. Apple makes sure that we're 
kept on top of new System Software developments (we tested 
Juggler, of course, for some time) because of TMON, but the 
applications that benefit from the knowledge first are a bunch of 
games! (ГИ bet we have the only MultiFinder-aware adventures 
on the market.) Also ironic is the fact that the Mac Venture kernel 
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MacScheme 


Paul Snively 
Lisp ICOM Simulations 
= MacTutor Contributing Editor 
MacTutor Vol. 4 No. 3 


seems to be a good testing environment for all kinds of weird 
issues like window management, application-defined events, 
synchronous and asynchronous I/O, and the like. 

Speaking of which, here’s a bug note for MultiFinder 1.0 that 
you may want to publish. If your application is MultiFinder- 
aware and has the canBackground bit set in its SIZE resource (i.e. 
it will run in the background under MultiFinder), and the appli- 
cation posts an application-defined event (appEvtl-appEvt3; 
appEvt4 is for Suspend, Resume, and mouseMoved events), the 
event will not necessarily get sent to the application that created 
it—it may go to some other application running under MultiFin- 
der. Needless to say, this can cause your application and the other 
application all kinds of headaches if you rely on application- 
defined events to work properly (the MacVentures historically 
have used appEvtl and appEvt2 for won/lost events and sound 
events; the kernel has been rewritten to be a state machine now 
that uses no application-defined events). 

It’s really been fun Lisping lately; I’d forgotten how nice it 
is to work in a good Lisp development environment. It’s been so 
nice and so accessible that I’ve gotten some really interesting 
ideas that I think (and in some cases know) could be implemented 
fairly easily in Lisp. One thing that comes immediately to mind 
is a Display PostScript implementation (Lisp is great for writing 
interpreters). Another thing that comes to mind is porting 
Xerox’s “NoteCards” program from their Lisp workstations to a 
Mac II running Common Lisp. The world seems to love Hyper- 
Card, so they should faint over “NoteCards.” 

Well, again, thanks for everything! Please say hello to the 
rest of the gang for me (and please tell Shelley that I enjoyed 
talking to her again very much). Hopefully ГІ see you in 
August!” Sincerely, Paul Snively 


The Cheap Al Workstation 


The Macintosh II has been around for a few months now, and 
much of the furor has died down, aside from gripes from 
disgruntled Macintosh П owners that Apple has been less than 
speedy in coming out with their own color monitor, or that more 
SIMMs are hard to come by. In some ways, the honeymoon is 
over, and we’re beginning to hear the complaints. People aren’t 
as blown away by the performance of the 68020/68881 as they 
thought they would be. Some software, particularly those pack- 
ages that insisted on breaking some of Apple’s clearly-defined 
rules, doesn’t work on the Macintosh II. Virtually all games that 
do animation of any sophistication at all don’t work because they 
use the alternate screen buffer, which the Macintosh II hardware 
lacks. 
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Му personal opinion is that, at least for developers if not for 
the end users, the honeymoon for the Macintosh II is ending 
before the marriage has even been consummated. I feel that 
there's been too much emphasis on why the Macintosh II is 
perhaps not as great a "souped-up Mac Plus" as some people 
might have wished, and not enough emphasis on why the Macin- 
tosh П is probably the most bang for the buck that you will be able 
to get in a low-end workstation for the next few years. 

When I was a computer science student in college, I thought 
the academic scene was pretty boring. By the time I was a 
freshman in college I’d been programming for four years already. 
Taking courses called “Advanced Programming Techniques" 
that consisted of learning the PL/I programming language and 
learning about such ostensibly innovative data structures as 
"linked lists" and the algorithms to manipulate them impressed 
me about as much as learning Latin would have as a high-school 
student (in fact, I find Latin a great deal more applicable to real- 
world situations than PL/I)! 

That was the obvious side of my college experience. The 
non-obvious side of my college experience consisted of getting 
to know two fascinating individuals and the language in which 
they seemed best able to express their concepts. The people were 
Douglas Hofstadter, author of Gódel, Escher, Bach: An Eternal 
Golden Braid, and Daniel Friedman, author of The Little LISPer. 
The language in question was, of course, Lisp, or at least one or 
two interesting variations on it. 

I learned Franz Lisp and Scheme on the VAXCluster at 
school on my own time. It was a wonderful environment to work 
in, and I spent many hours in front of my Model I TRS-80, which 
was connected to the phone in my dorm, and from there con- 
nected to the computing network on campus. I had access to a 
wonderful Lisp structure editor, and, Lisp being the kind of 
language that it is, I spent a fair amount of time customizing my 
copy of the editor to suit my tastes. It was fairly easy, if also fairly 
dangerous, because I could literally change the editor, and as 
soon as I entered the change, it would take effect. Needless to say, 
it was quite possible to goof and do something to make the editor 
totally unusable this way, so working on a backup copy was 
always a good idea. But to me, Lisp was always the ultimate 
interactive development environment, and the concepts behind it 
were extremely interesting. 

By now you're probably wondering where all of this is 
leading up to. Well, bear in mind that I was working on a large 
VAXCluster with lots of disk space and lots of memory—and 
lots of horsepower. I gota Lisp for my TRS-80 at one point, but 
it turned out to be a very frustrating thing, what with the limited 
RAM and CPU power of most 8-bit micros. I basically resigned 
myself to never working in such an environment again, and since 
I had become entrenched in the microcomputer world, I figured 
that I'd never have a good Lisp system. 

Time wenton, and although decent Lisp systems got smaller 
and created a whole new class of machines called “worksta- 
tions," which had names like Symbolics and Lisp Machine, 
those, too, were machines with alot of horsepower and RAM and 
disk space, dedicated to doing one thing: running Lisp, and 
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running it well enough so that professional AI researchers could 
do meaningful work. They were obviously still way out of my 
league as an interested amateur, with price tags well into the five 
figure range. 

But the Macintosh II exists now, a machine with an 
MC68020 microprocessor, an MC68881 math coprocessor, 
anywhere from 1 to8 megabytesof RAM, and as much disk space 
as you can afford. It's not a dedicated Lisp machine, but with a 
couple of Macintosh products available, it might as well be, and 
it's a lot cheaper. 

I picked up two Lisp implementations at the Boston 
MacWorld Exposition. One of them is a newcomer, released at 
the show. The other has been around somewhat longer, but has 
undergone some evolution and deserves a serious look. What is 
perhaps most interesting about the two products is that while they 
both cover extremely similar ground, because of their underlying 
philosophies they will appeal to different people and for different 
reasons. 

MacScheme+Toolsmith 1.0 is the older of the two products 
that I have, or at least MacScheme is. In chapter one of the 
documentation, it says: "MacScheme, introduced in August 
1985, was the first microcomputer implementation of any mod- 
ern Lisp standard." It's a rather bold statement, and one open to 
question if you have used some of the other Lisp offerings on 
other machines, particularly any of the Golden systems on the 
ІВМ PC-class computers. Оп the other hand, if you accept 
Semantic Microsystems’ statement that “Scheme is one of the 
two major dialects of Lisp," and understand that the other one is 
Common Lisp, and also know that until very recently there was 
no such thing as a complete microcomputer implementation of 
Common Lisp, then the statement is certainly true. 

MacScheme historically has been а semi-compiled, byte- 
code oriented system, but with the addition of the Toolsmith 
code, MacScheme has become a language capable of compiling 
to native code and creating standalone applications written 
entirely in Scheme. Scheme aficionados should find this very 
exciting. Complete source code for a simple text editor is 
included to help show how to create applications. The choice of 
a texteditor is an interesting опе; I guess the message is that “Lisp 
isn’t just for AI anymore,” which is certainly a valid point. 

If there’s a general way to describe Scheme, it has to include 
the word “elegant.” Scheme was designed with an eye toward 
simplicity and power. It tends to be the smallest implementation 
of Lisp for any given machine, and MacScheme+Toolsmith is no 
exception to that rule; the kernel is about 75K in size, and a 
goodly-sized heap image is about 182K. 
MacScheme+Toolsmith fits pretty well in a one megabyte 
machine, as long as you’re careful about hogging up valuable 
RAM with things like debuggers and INITs and sounds and so 
forth. 

MacScheme+Toolsmith 1.0 is shipped on three 800K disks, 
labelled “Toolsmith,” “Library,” and “Miscellaneous.” Don't be 
misled by the fact that the whole product takes 2,400K of disk 
space to ship; you can copy the Toolsmith disk, boot from it, and 
accomplish a great deal without ever looking at the other two 
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disks. Тһе Toolsmith disk contains a System Folder, the 
MacScheme+Toolsmith application, a generic Scheme heap 
image file, and a Toolsmith heap image file. Double clicking the 
application will cause MacScheme+Toolsmith to look for 
*Scheme.heap;" you can double-click any heap image file to 
cause MacScheme+Toolsmith to load it instead. 

Once MacScheme has come up, you'll see one thing that 
immediately sets it apart from Allegro CL, the other Lisp envi- 
ronment that I wish to look at: MacScheme has a fairly spartan 
user interface. It's too easy to be put off by the minimalist 
appearance of the product. Avoid the temptation. While the tools 
to tinker with MacScheme may not be as obviously up front and 
*Macish" as they are in Allegro CL, they are, for the most part, 
there. MacScheme is a complete Scheme implementation, and, 
like Scheme as a dialect, is minimalist in philosophy, preferring 
to be extended via available source code (of which there is plenty 
with MacScheme+Toolsmith) rather than providing everything 
up toand including the kitchen sink as part of the language kernel, 
which is more Common Lisp’s style. 

MacScheme offers a transcript window and four menus as its 
user interface upon booting. The transcript accepts invocations 
of Scheme expressions and returns their value in a fashion that 
should be familiar to anyone who has used a command-line 
interface before. The four menus are pretty much what you'd 
expect, especially considering that any Macintosh application 
that claims to follow the user interface guidelines must have the 
first three. The four are the Apple, File, Edit, and Command 
menus. 

The Apple menu simply has the standard fare: an “About...” 
box that tells a bit about who's behind MacScheme with some 
copyright information, and whatever desk accessories are avail- 
able on your system. 

The other menus can, and do, vary somewhat from applica- 
tion to application, so let's look at them more closely. Here's the 


File menu: 
EIN Edit Command 


хрен а 
Ореп... 

t ibse 
Save 
Save as... 
Page Setup... 
Print... 

Quit 


Figure 1 


There’s certainly nothing radically different about this File 
menu; it contains pretty much what you expect to see in a Mac 
application. “New” creates a new Scheme source file for you to 
putcode in. “Open...” opens an existing source file. “Close” will 
close the current file if there is one. “Save” saves the file’s 
contents. "Save as...” allows you to save а file’s contents in 
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another file. “Page Setup...” allows you to define your printing 
options. “Print...” prints the file’s contents on the chosen printer, 
and “Quit” ends your Scheme session. 


Here’s the Edit menu: 


& 
Lopt sC 
Paste (IU 
t (leac s 


BUR 


Figure 2 


All of the Edit тепи’$ functions are standard with the 
exception of the last two: “Pick” and “Indent.” Both of these 
functions are Scheme-specific. “Pick” uses a simple heuristic to 
pick the nearest Scheme expression. For example, if the vertical 
bar is blinking behind a closing parenthesis, using “Pick” will 
select back to the matching open parenthesis, assuming that the 
parenthesis enclose a complete Scheme expression. Note that 
there are a couple of ways to invoke Pick: you can use the menu 
or the Command-key equivalent. 

“Indent” can be used when you're editing some Scheme 
code to reformat its appearance. Like most Lisp editing systems, 
the editor in MacScheme will automatically indent as you enter 
the code so as to keep it readable. This is fine for when you're 
entering the code from scratch, but editing can ruin the format. 
Hence the necessity for something like “Indent,” which operates 
on the current selection. The Tab key also serves this purpose. 

Now let's look at the Command menu: 


File Edit Cammond 
сна! е}. 


Pick & Ша! 86 LU 
cScheme" Тор Reset R 
| Вгеак 38B 
Trim T 
Pause 888 
E DRINKE 25 


Sham Тали 
Figure 3 


This menu is all Scheme specific, as you might expect. The 
first function is the most obvious one for a Lisp system: “Eval.” 
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It evaluates the currently selected Scheme expression, printing 
the value in the transcript. 

The second item, "Pick & Eval," is the most frequently used 
one. It does what it says, combining the functionality of “Pick” 
from the Edit menu and “Eval” just mentioned. Since this 
combination is so frequently used, it can be invoked three ways: 
by choosing the menu item, by pressing the Command-key 
equivalent, or by pressing the Enter (not Return) key. 

The next item, “Reset,” is handy when some process has 
been interrupted and seems irrevocable. Resetting the system is 
the next best thing to quitting and starting again. It eliminates all 
your definitions and side effects from the time you brought up 
MacScheme. 

Next comes “Break.” This is used to interrupt a Scheme 
process. It puts you into MacScheme's debugger so that you can 
examine variables, the stack, or results of evaluating expressions. 
You can continue execution from the debugger as well. 

"Trim" isa housekeeping function thatcuts off all but the last 
page of the transcript. It's useful for when the transcript gets too 
long and seriously degrades the performance of the system. 

"Pause" allows you to stop whatever is going on so that you 
can see what's on the screen. “Continue” is its counterpart, and 
doesn't become active until Continue" has been used. They 
have the same Command-key equivalent so that you can pause 
and go with a single Command-keystroke. 

"Show Transcript" is a convenient function for bringing the 
transcript window to the front when you have several windows 
open. That's a desirable thing, since that's where all the action 
is. 

Believe it or not, that's really all there is to MacScheme's 
user interface. Of course, with MacScheme+Toolsmith, you 
have access to the Toolbox and, in the case of some user interface 
elements such as menus and windows, you have a pleasant 
pseudo-object-oriented interface to them, so you can certainly 
add your own menus with your own tools; indeed, I'd recom- 
mend it. In particular, if someone has a Scheme version of 
Common Lisp's “Аргоров,” I'd certainly love to see it. 


Now let's contrast this user interface with that of Allegro 
CL. Before I do, I'd like to point out to those who might be 
wondering why I'm concentrating so much on user interfaces 
that I am an environment freak, which is to say that I believe that 
the programming environment is what makes the system usable/ 
more productive/more fun or what have you. A good example of 
a great environment to work in is Smalltalk-80's. Smalltalk-80 
as a language is a very nice object-oriented one with a lot to 
recommend it—things like consistency, flexibility, and power. 
Smalltalk-80, however, is also very huge and very complex by 
most language standards. To make matters worse, programs that 
are written by a Smalltalk-80 user simply become part of the 
overall environment. There isn't any distinction made between 
code that the language provides and code that the user writes. So 
if you extend an already huge language by adding several 
megabytes of user code, you wind up with a potentially larger 
mess. 
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That's why Smalltalk-80 includes several tools for doing 
what, in total, I call “managing complexity." In the most general 
sense, anytime a programmer creates a tool or environment that 
doesn't have a direct effect on the functionality of the code that 
s/he is writing, s/he is managing complexity (MacApp, for 
example, is a very good attempt to manage the complexity of 
writing a Macintosh application with a good, reliable, standard 
user interface). 

There are essentially two schools of thought on program- 
ming environments: the school that says “thou shalt conserve 
disk and memory space and gain development efficiency and 
productivity by disciplines such as structured programming,” 
and the school that says “given sufficient disk and memory space, 
gain development efficiency and productivity by having all 
System source online at all times; have a programmable, custo- 
mizable editor; have excellent stepping, tracing, stack frame 
analysis, and other debugging tools; have tools that make the 
many megabytes of mess easy to access so as to get what you 
need, and have all this in one consistent environment.” (Of 
course, some people will argue that there are two kinds of people: 
those who believe that there are two kinds of people and those 
who don’t, but that is another story.) 

The first school of thought is that espoused by virtually every 
common development environment in use today. Think about it. 
Disk space is considered an expensive “plus,” with memory 
being treated similarly. Most popular languages today (Pascal, 
C, assembler) do not encourage the idea of extension of the 
language by the user; languages that do (FORTH, Smalltalk-80, 
Lisp) are out on the “lunatic fringe” of programming society. 
Virtually no development environment includes its complete 
source code (and, to be fair, there are valid commercial reasons 
for wishing to avoid this), but Smalltalk-80, for example, likes to 
present you with complete source code online at all times—one 
reason that it usually takes at least 10 meg of disk space to run 
Smalltalk-80. High-level implementations for the Smalltalk-80 
byte-code primitives (the things actually implemented in the 
machine language of the target computer) are even included so 
that you can see how the algorithms work. 

When dealing with such large quantities of code, something 
more than aclassical text editor is needed. Smalltalk-80’s answer 
to this 15 the browser, which is a special kind of editor that divides 
all of the code in the system into manageable chunks (in Small- 
talk-80's case, this is facilitated by its object-oriented nature). А 
simple means of getting to any particular piece of code in the 
system is provided. 

Common Lisp is the Lisp world's answer to Smalltalk-80, 
and it tends to reflect that fact by being somewhat larger than 
other implementations. To give you some idea as to what I mean 
by this, the Allegro CL application just barely fits on an 800K 
disk. Contrast this 750+K kernel to MacScheme's 75K. 

You may wonder why an implementation like Allegro CL is 
So large. Most of the answer to this question can be found by 
looking at a copy of Common LISP: The Language, by Guy L. 
Steele, Jr. This book completely defines the Common Lisp 
language standard, and it's not the sort of thing you're going to 
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finish reading over a, say, six hour airline flight unless you're ап 
incredibly fast reader. 

. At least two or three other Lisps for the Macintosh (the 
public-domain XLISP, and ExperLisp and ExperCommonLisp, 
the latter two from ExperTelligence) have been subsets of 
Common Lisp to one extent or another, and some people who use 
a complete Common Lisp on a workstation, mini, or mainframe 
at work are leery of these products, particularly if they plan to 
convert their Common Lisp code to run on the Macintosh. Users 
of Allegro CL have fewer worries, since Allegro CL is the only 
complete implementation of Common Lisp on any mass-mar- 
keted microcomputer as of this writing. (When doing conver- 
sions, you still have to worry about the things you always have 
to worry about, even when going from Common Lisp to Common 
Lisp—things like macro translation, what packages are available 
in any given implementation, etc.) 

So what does this Common Lisp environment look like? 
Let's find out. First, the menus: 
"Erie Edit Eval 
‚| About Allegro CL.. 


Tools Windows 


өөө 


Suitcase %К 
InterMail 
Rccess Privileges 
Rcta 
RffinieFile 
Alarm Clock 
Calculator 
Camera 
Canvas DA™ 
Chooser 


Figure 4 


This is a pretty standard Apple menu, with the “About...” 
item for Allegro CL and, in my case, oodles and oodles of desk 
accessories, thanks to Prof. Mac (aka Steve Brecher) and Suit- 
case. The “About...” box for Allegro CL is a little unusual 
because it does more than just tell you about Allegro CL; it also 
tells you what you're running on: 


Allegro CL Version 1.1 


Running On: 

Macintosh 1! 

68020 with MC68851, Apple Desktop 
Bus, MC68881, SCSI port 

Rom Uersion 120 

Macintosh System File Uersion 4.2 


Copyright 6 1987 by 
Coral Software Corp. k 
and Franz inc. 
Вон 507 
Cambridge, МВ 02142 
USR 
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Well, it isn't perfect. First of all, when it has too much 
information to present, it wraps it around without re-indenting, 
which isn't good aesthetically. More importantly, it thinks that 
my Mac II has an MC68851 installed, which it definitely does 
not. 

Next is the ubiquitous File menu: 


ПЕ Edit Eval 
New N | 
Open... 360 | 
Dpen Selected File 
Close 

Save 


Save As... 
Revert 

Page Setup... 
Print 

Qui 


This looks a lot like the File menu from other development 
environments, with the typical “New,” “Open...,” “Close,” 
“Save,” “Save As...," "Page Setup...,” "Print," and “Quit” 
choices. The “Open Selected File” and “Revert” choices are 
desirable but not found in most environments, so seeing them 
here is a pleasant surprise. 

Next is Edit: 


Eval Tools Windows 


Unio 


Cut 38H E 
Copy 3C | 
Paste 980 | 


Clear 
Select RII aen x 


Insert Killed String.. 


Search... 
Change Font... 


"aaa... КУЛЛ ЛЛУ ОО КУЛУ ж а тк як ққ ик, 
RC ee SSS ИЛИИ NN 


Figure 7 


Here’s another menu with few surprises, with the possible 
exception of “Insert Killed String...” which relates to the Allegro 
CL editor, called FRED (more about FRED later). I won’t insult 
your intelligence by going through all of these common func- 
tions. 
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Now for Eval: 


€ File Edit Ш 


ЕКТІ 


КРИ) 


Tools Windows 


Eval Selection ЖЕР. 
Eval Buffer 

Load... 
Compile File... 


Rbort 96 
Вгеак 86, 
lLontinue 5; 


идиот 
ИМИ ИМИ ИИ, 


Figure 8 


This menu is a little more Lisp-specific, but still pretty 
intuitively apparent. “Eval Selection" does just that, and it’s not 
particularly picky about where the selection is, either. If the 
selection is a valid s-expression, it will be evaluated. 


"Eval Buffer" is handy when you've made some fairly 
extensive changes to a source file. Just make the file's window 
the active window and choose this menu item. It's equivalent to 
choosing “Select All” from the Edit menu, then choosing “Eval 
Selection." This probably won't be used often, however, since 
Lisp is incrementally compiled, which encourages editing and 
recompiling individual definitions since the effects are system- 
wide, rather than forcing you to recompile all definitions follow- 
ing the one that you changed in the source code. 

"Load..." puts up the Standard File Dialog showing Allegro 
CL source files so that you can load one. Loading a file is simply 
a quick way of opening it and eval'ing the buffer; the only 
difference is that it's a one-step operation and doesn't create a 
window for the file in question. 


"Compile File..." allows you to create a file of Lisp that's 
compiled down to MC68000 machine code. Such files have the 
extension ".fas]" as opposed to “.lisp,” and have the advantage of 
loading considerably faster than their textual counterparts, as 
well as making it tough to figure out how something does what 
it does (Coral Software distributes their Dialog Designer soft- 
ware with Allegro CL 1.1 as a “.fasl” file; apparently the Dialog 
Designer is proprietary). Note that Allegro CL does not currently 
create standalone applications, though Coral has promised that 
capability for the near future. 


The last three items are familiar and basic debugging tools, 
good for stopping a Lisp process in midstream, tinkering around 
in the current lexical context, and continuing (or not) as you see 
fit. 

"Tools" is where most Allegro CL users will probably find 
themselves spending some time: 


O The Definitive MacTutor, Vol. 4 


€ File Edit Eual 


Windows 
List Definitions 
Edit Definition... 
Apropos... 
Inspect 
Backtrace 


ово ооо соо ово ооо ооо ооо Ф: 0000000000099 


Documents... 
Fred Commands 


Print Options... 
Environment 


The first item is rather interesting; it's a function that lists all 
definitions within a particular FRED buffer (whichever one is 
active when the menu item is chosen). In order to do this, it must 
go through the entire buffer looking for DEFUN and DE- 
FOBJFUN and so on (can you say "heuristic?" I knew you 
could)! It then creates a dialog box containing the names of the 
definitions: 


ЕЕЕ 


=== s Definitions in Listener 


find-route 


(6) Buffer Order 
O Riphabetical Order 


[ бо To Def | 


Figure 10 


You can then select a function and click on *Go To Def" to 
rapidly see the source code for the definition (double-clicking on 
the name willalso rapidly get you there). You can view the names 
by their order in the buffer or alphabetically. You can also rescan 
the buffer in case it's changed since the last scan. This is part of 
that “management of complexity" that I talked about earlier 
(easily getting to definitions in large bodies of code). 

"Edit Definition..." is similar; it brings up a dialog into 
which you type the name of the function to edit. In this case, the 
file in which the function was defined doesn't even have to be 
open; Allegro will open it and find the definition for you. In fact, 
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if the function has been defined more than once and from 
different sources, another dialog will open indicating the order of 
the multiple definitions (with the most recent being last) and let 
you choose which version to edit. I find this feature very 
impressive. 

“Apropos...” is for people like me who just can’t remember 
what the name of that function is... I use the extended version of 
Apropos which is included with Allegro CL 1.1 as source code. 
It brings up this dialog: 


” é File Edit Eval ҮЙ Windows 


Apropos 
Value Binding Types 
У variable 


& constant 
П unbound 


Oand QGor 
Function Binding Types 
6d function 
Ы macro 
ËJ special form 
[] unfbound 


Packages 


CCL 
KEYWORD 


О inherited 
J internal 
64 external 


Substrin First Character 
4% 638 &upper-alphas 


64% DQ. others 
| ок | 


[X] upper-case substring 
С] sort output @ print O inspect 


Figure 11 


As you сап see, you have a lot of choices to make about what 
Apropos will and will not look for. You can choose what Value 
Binding Types to look among, and/or what Function Binding 
Types. You сап select the packages to look among, and whether 
to look for inherited, internal, or external symbols. You can limit 
your search by first character (thereby only searching things that 
are, by generally accepted typographical standards, global vari- 
ables, for example). You can optionally sort the output, and 
either print it or inspect it. 

For all that, what this is really all about is typing some 
substring into the “Substring” field and letting Allegro list all the 
symbols that a) meet the criteria specified in the dialog and b) 
contain the substring that you specified. For example, with the 
above dialog, here's the list that the substring "button" gets you: 


:RADIO-BUTTON-CLUSTER 

:BUTTON2 constant value: :BUTTON2 

‘BUTTON! constant value: :BUTTON1 

:BUTTON-STRING constant value: :BUTTON-STRING 

:DEFAULT-BUTTON-ENABLED constant value: :DEFAULT-BUTTON- 
ENABLED 

:DEFAULT-BUTTON constant value: :DEFAULT-BUTTON 

‘OK-BUTTON-TITLE constant value: :OK-BUTTON-TITLE 

:RADIO-BUTTON-PUSHED-P constant value: :RADIO-BUTTON-PUSHED- 


constent value: :RADIO-BUTTON-CLUSTER 


P 

:DIALOG-BUTTON-ENABLED 
ENABLED 

CCL : :RADIO-BUTTON-DI-TO-SOURCE 

CCL : :BUTTON-DI-TO-SOURCE 


constant value: :DIALOG-BUTTON- 


function 
function 
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XRADIO-BUTTON-DIALOG-ITEM* value: 8<0bject 877, *RADIO- 
BUTTON-DIALOG-ITEM*, а CCL::*CONTROL-DIALOG- I TEM*) 

*BUTTON-DIALOG-ITEM* value: &‹06јесі 875, *BUTTON-DIALOG- 
ITEM*, а CCL: :*CONTROL-DIALOG- ITEM*) 

-BUTTON constant value: 43380macro 


Next comes “Inspect,” Common Lisp's answer to Small- 
talk-80's browser (at least in most respects). Choosing it brings 
up this dialog: 


Inspect 


Inspect System Data 
Choose Inspect Window 
Inspect History 

Type In 

Print Top Window Form 
Top Buffer Pathname 
Update Top Window 
Close Inspect Windows 
Close Unmoved Windows 


Figure 12 


Coral Software has wisely made “Help” the first choice in 
the dialog. It brings up a text file with some helpful, if somewhat 
terse, pointers on how to take advantage of Inspect. 


The next item, “Inspect System Data,” is extremely useful, 
especially for those just getting into Allegro CL. It shows this 
window: 

s $$ {ет Data 


(devices) 

Logical Pathnames 
Search Files 

Find Files 


Cwindows > 

жу indow* 

ж fred-windou* 
( front—window > 
*top-|istener* 


(menubar 2 
*тепи* 


*features* 
Clist-all-packages) 
жраскасе* 
*readtable* 


Record Types 
Record Field Types 


| INSPECT | 


Ғідиге 13 
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This window allows you to "inspect" information (and, in 
some cases, manipulate it) that can be of some value to you and 
to the system. The first choice in the list is *(devices)," which, 
as you might expect, tells you about all currently online volumes: 


Devices 


Tumbolia: 


| INSPECT | 


(windows 2 
*yindou* 
* fred-windou* 
€ front—window > 
*top-listener* 


(menubar 2 
*menu* 


*features* 
Clist-al 1-раскадеѕ > 
*package* 

*readtable* 


Record Types 
Record Field Types 


| INSPECT | 


Figure 14 
As you can see, I only have one device: my internal hard 
disk, "Tumbolia." Double-clicking on it gets me this dialog: 


"Tumbolia:" 


Directory Operations 
Tumbolia:Apprentice f: 

:Beyond Zork f: 

: Canvas 

: Cash Disbursements Stacks: 

: Communications 
Tumbolia:Desktop 
Tumbolia:Dollars & $ense 1.4: 
Tumbolia:FEdit 
Tumbo І ia: HyperCard 
Tumbolia:HyperCard Stacks: 
Tumbolia:LISP f: 
Tumbolia:Literary Machines 
Tumbolia:Lurking Horror f: 
Tumbolia:MacUenture f: 
Tumbolia:McAssembly f: 
Tumbolia: MPH: 
Tumbolia:Path Mockup 

: Path: 

:Paul Mercer's Greatest Hits: 

:Phone Extensions 
Tumbol ia: QUED/M 


k 


| INSPECT | 


Figure 15 
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The inspector can perform some Finder-like functions 
through the Common Lisp file system. There are dialogs for file 
operations (for those items that don't end with a colon, i.e. those 
that are files) and directory operations for the ones that do, i.e. are 
directories. You can copy, delete, load, compile, edit (if it’s atext 
file), and so on, all without leaving Allegro CL. 

Other file-related functions available from “Inspect” in- 
clude the inspecting of logical pathnames (Common Lisp was 
designed to work on large systems with hierarchical directory 
structures, e.g. UNIX-based machines and VAXes running 
VMS. Macintoshes from the 512K Enhanced up fall neatly into 
this category as well). Common Lisp defines some logical 
pathnames; Allegro CL provides some more, and you, the pro- 
grammer, can define still others to make your life easier (much 
as MPW users can define symbols to refer to complex paths to 
various files). 

А pathname can also be searched for a string, and the 
pathname being searched can contain wildcard characters, allow- 
ing you to define clearly the places to look. “Inspect” сап also list 
all pathnames that match a certain wildcard string. 

"Inspect" can also tell you about several system data struc- 
tures, such as the currently open windows: 


=== List: *<Object #203, System Data, а 


List Operations 


0 *«Object 9203, “System Data”, a CCL: :*RCTION-SEQUENCE-DIRLOG*» 


1 


z Ясный 8172. 


®<Object 9199, "Inspect", а CCL: : *ACTION-SEQUENCE-D I ALOG*> 


Listers о СП: ІЗТЕНЕР; > 


Figure 16 

At the time that I double-clicked on “(windows)” in “In- 
spect,” there were only three (at least in that MultiFinder layer)— 
“System Data,” “Inspect,” and “Listener.” In Allegro CL, you 
see things referred to as “objects” quite a bit, and they don’t mean 
Lisp data objects, either. Allegro CL is an Object Lisp implem- 
entation, and when it says that “Listener” is a 
“CCL::*LISTENER*,” it means that “Listener” is a specific 
instance of an object called **LISTENER*" that was defined in 
the “CCL” package. 

Let’s see what “Inspect” can tell us about “Listener:” 


Parents: (9«Object 99, CCL::*LISTENER*, а 92, CCL::*SELECTION-STRERM* . 
Ancestors: (9«Object 99, CCL::*LISTENER*, а 92, CCL: :*SELECTION-STREA.. T 
Variable bindings: Ara 
: РАОМРТ-МЯЯК = <A MARK> 

: :START-MARK = 8<A MARK? 

: :EOF-MRRK ж 9«R MARK> 

:RERD-MRRK = <A MARIO 

::TV0-COUNT = O 

: :PENDING-NL = NIL 

: :UNDO-HRNDLE = 8<A МАС Handle 18205C> 

: :REDO = NIL 


: :UNDO-STRING = NIL 
: :UNDO-FUNCT ION = NIL 


BBRBRBBBBRBR 


: :UNDO-MODCNT = NIL 
COMTRB = 8<R COMTRB» 
CCL::BLINK-TICKS = 490970 
CCL::CLICK-TICKS = NIL 
CCL::CLICK-POS = NIL 
CCL::G0RL-COLUMN = NIL 
LAST-COMMAND = NIL 

CCL: :DEFS-DIALOG = NIL 
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Тһе window gives us the object's ancestry in the object 
hierarchy along with the object's variable and function bindings. 
Values are shown for the variables bound to the object. 

The list goes on and gets quite long. Let's move on from 
“Inspect” and look at some other things. 

Back in the “Tools” menu, “Backtrace” is something that 
can become enabled under certain customizable conditions, such 
as on an error. Choosing it gets you something like this: 


5 Stack Backtrace z 


e 
CCL: : RERD-LOOP | 
© 


CCL: : TOPLEVEL-LOOP 


Frame:  MRPCRR (3 values) 


(CJKLNHDOC(UJKLNIDCJINHMMPCJI NH KO 
<РНОМЕ 2 
9«R COMPILED-LEXICRL-CLOSURE . > | 


Figure 18 


When we got here we had a message indicating that there 
were too few arguments to MAPCAR (the one immediately 
preceding the ERROR in the Backtrace). The Backtrace shows 
us everything that had been evaluated until the error occurred, 
including Allegro's top-level loop, all the way down to the 
function that reported the error. 

Each function has a frame in which bindings are stored, and 
those frames can be examined by selecting the function whose 
frame you're interested in. In the case of the MAPCAR that had 
the proper number of parameters passed (or so we think— 
MAPCAR takes optional parameters), the frame shows us three 
things: a compiled lexical closure that doesn't have a name 
(because it was written as a LAMBDA expression and passed 
straight to MAPCAR) and two lists, the first (reading from the 
bottom up) of which contains the atom "PHONE" and the second 
of which contains several lists of atoms. Clicking on one of the 
values shown here will assign that value to the global variable 
**DEBUG-V ALUE*" so that you may do with it whatever you 
wish or need to aid in debugging. 

“Documents...” is a shortcut to opening a file in the logical 
pathname "ccl-doc;" which contains several files documenting 
certain aspects of Common Lisp and Allegro CL in particular, 
including such Common Lisp esoterica as reader macros, the 
character set of the language, argument lists for exported sym- 
bols in the LISP and CCL packages, and so on. Some of these 
things are brought up automatically when other functions are 
performed (for example, a keystroke while the cursor is within 
most Common Lisp functions will get you its argument list in 
case you need reminding), but this is a good way to do itexplicitly 
or to get other kinds of information. 
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Nextis “Fred Commands." Thisisauseful function notonly 
because it can remind you of the standard FRED commands, but 
it can remind you of non-standard ones as well. I should explain 
that comment by pointing out that “FRED” stands for "FRED 
Resembles EMACS Deliberately." The powerful EMACS edi- 
tor was originally written as a collection of TECO macros, but 
was eventually made standalone by RMS (Richard M. Stallman), 
the last of the true hackers from MIT. EMACS has since been 
commercialized and rewritten (mostly in C) and become almost 
respectable, but for Allegro CL, FRED remains what EMACS 
really was: a programmable Lisp editor. 

A key idea behind EMACS (and therefore FRED) is that a 
function can be bound to each and every key on the keyboard. 
The bindings are kept in a data structure called a COMTAB 
(command table). For most normal keystrokes the function 
simply inserts the proper ASCII value at the current buffer 
position, thereby making the keys behave as you would expect. 

EMACS expects several other keystrokes to be available, 
though, thanks to two modifier keys, control and meta. The 
Macintosh keyboard historically has had command and option 
keys, with control being a recent addition not present on all 
keyboards. 

For this reason, Allegro CL offers two modes of operation: 
Macintosh mode and EMACS mode. In Macintosh mode, the 
command key is the command key and shift-command is the 
control key. In EMACS mode, this functionality is reversed. In 
either case, the option key serves as EMACS’ meta key. If the 
keyboard has a control key, it will serve as the control key as well 
(on such keyboards, using Macintosh mode is a good idea). 

Since EMACS can redefine the function of the keys, the 
‘Fred Commands” function must determine what those func- 
tions are at run-time, and that is what it does. Here is what you 
see when you choose this function: 

Figure 19 


Fred Commands 


Global command table: 
с = control [the shift + cloverleaf keys) 
m = meta [the option key] 


Enter ED-EURL-OR-COMP I LE-CURRENT -SEXP 
Backspace ED-RUBOUT-CHRR 

m-Backspace ED-RUBOUT WORD 
c-m-Backspace ED-DELETE-BHD-DEL | MI TERS 
Tab EDEN d'amis 


This isn'ta complete look (the scroll bar is active), but it will 
give you some idea as to what can be done in EMACS. Pressing 
the Enter key will evaluate the function "ED-EV AL-OR-COM- 
PILE-CURRENT-SEXP,” which in English sounds like “Evalu- 
ate or compile the current symbolic expression." In other words, 
depending upon the context, the s-expression pointed to by the 
cursor will either be eval'ed or compiled. Note that when 
EMACS says Enter, it means Enter, not Return. 

The Backspace key evaluates "ED-RUBOUT-CHAR," 
which makes sense. Meta-Backspace does "ED-RUBOUT- 
WORD,” which in light of what the prefix “meta” literally means 
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also makes sense. Control-meta-Backspace eval's *ED-DE- 
LETE-BWD-DELIMITERS," a function that deletes backwards 
until it finds a matching delimiter (good for removing entire 
parenthesized expressions). 

The function for the Tab key is interesting: “ED-INDENT- 
FOR-LISP." The implication is that you couid bind а function to 
Tab that would indent for C, or for Pascal, or what have you, and 
of course, that is the case. 

EMACS also supports the concept of a “kill-ring,” which 
you can conceptualize as kind of round-robin clipboards. The 
most recent kill-ring is the clipboard, as a matter of fact, which 
brings us back to the "Edit" menu and "Insert Killed String..." 
This menu item will open a dialog showing the entire kill-ring, 
and allow you to select any of the available killed strings to be 
pasted into the current buffer. Using the standard “Paste” menu 
item will use the most recent string. 

The "Print Options..." and “Environment...” choices allow 
you some control over the Lisp world that you live in. You can 
choose to pretty-print or not, to print circular structures or not (to 
do so can hang your machine, however), to use EMACS mode or 
not, and so on. Note that many of these values can be set in the 
"init.lisp" file that Allegro CL loads automatically when it is 
launched. FRED programming can also be done within 
"init.lisp" for further customization of the environment. Menus 
can be added and/or changed from "'init.lisp" and so forth. 

Another great feature of Allegro CL is their single-stepper. 
The "STEP" function is defined in the Common Lisp standard, 
but the implementation is left pretty much up to the individual 
Common Lisp vendor. Allegro CL's stepper is wonderful. 
Suppose that I have a function called *FIND-ROUTE" that, 
when given a maze in the form of a list of connected rooms, a 


CIF COR САТОМ STRUCTURE? CMULL STRUCTURE? CNOT САТОМ START)? > 
COR CATON STRUCTURE) (NULL STRUCTURE) (МОТ САТОМ STRRT)) М 
CLET <(8:625 САТОМ 5ТВИСТИНЕ222 CIF 9:625 ®:G25 COR (NULL 


САТОМ STRUCTURE > 


STRUCTURE = ((R X) (A C? (Я D) СЯ OD (R H) ...) 


NIL 


82:625 = NIL 


COR CMULL STRUCTURE? CNOT CATON START)> «MOT CATON соя... 
«КЕТ ((8:626 (NULL STRUCTURE))) CIF ®:G26 9:626 COR [| 


[] Keep output window 


Figure 20 


starting point, and an ending point, prints the most efficient 
route(s) to get from start to finish. Let's also suppose that I have 
a maze whose symbolic name is “CASTLE,” with starting point 
“K” and ending point "PHONE." To step through this function, 
I would type: 

(step (find-route castle ‘К *phone)) 

and would see something like that shown in figure 20, after 
a few steps. 
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CIF 9:625 8:625 COR CNULL STRUCTURE) «МОТ CATON START >> { 


The stepper tells things the way they really are, which can be 
confusing at times. For example, I practically never use “IF” in 
Lisp, preferring the more complex, but more flexible “COND” 
instead. Allegro CL fools те—“СОМО” is a macro which 
translates to nested "IF"s, which is why you see “IF”s in figure 
20 and none in the Common Lisp code below. 

The stepper also evaluates things that are about to be used in 
a conditional so that you can see why the conditional is about to 
evaluate to what it is about to evaluate to. In the above example, 
the code asks “(АТОМ STRUCTURE),” so the stepper oblig- 
ingly mentions that “STRUCTURE?” is a list of lists, and so the 
question “ATOM” is answered “NIL.” 

The stepper has several functions. The most obvious one is 
“step.” A step in the function can also be "skip"ped. You can 
"eval" something in the current lexical environment, should you 
need to. You can also "replace" a step with another expression. 
You can issue a “break” in case you need to do something like 
look at a Backtrace. You can "finish" stepping and let the 
function complete without further ado, or you can "quit" stepping 
and cancel the current function's evaluation. For any of these 
choices, you can also keep the current contents of the stepping 
window after the stepping is over in case you need to scroll 
through it to see what was going on. As a newcomer to Common 
Lisp, I have found this stepping power to be indispensable. 

Believe it or not, I’m finally finished talking about the Com- 
mon Lisp programming environment. For the next (and last) few 
pages, I'd like to point out some differences between 
MacScheme and Allegro CL as dialects of Lisp rather than as 
programming environments. 

Scheme and Common Lisp both have similar roots. The 


commonality of them probably 
stems from basically one person 
who was highly influential in the 
creation of both dialects: Guy L. 
Steele, Jr. Both Scheme and 
Common Lisp are lexically 
| scoped languages, which sets 
L them apart from older dialects of 
Lisp, which were dynamically 
scoped. Both Scheme and Com- 
mon Lisp lend themselves to 
solving thorny problems in arti- 
ficial intelligence, logic, mathe- 
matics, and other symbolic 
tasks. Both dialects were speci- 
fied with speed in mind (e.g. to 
be a complete Common Lisp, an 
implementation must include both an interpreter anda compiler). 

Scheme differs from Common Lisp and other Lisp dialects 
by making functions first-class data objects, i.e. by putting them 
on equal footing with everything else. LAMBDA expressions in 
Scheme evaluate to a function, which can be assigned to a 
variable, passed to MAPCAR or other functions that take a 
function as a parameter, etc. 

Common Lisp doesn’t make it quite that simple. If you 
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intend to pass a function to another function, you'd better call it 
a function first, even if it is obviously one (because it's a 
LAMBDA expression or whatever). 

Scheme's simplicity allows it to support direct access to 
some relatively deep internal structures, such as continuations. 
For us C and Pascal folks, we might want to think of continu- 
ations as being analogous to stack frames. А continuation 
represents the state of a function's execution as it calls other 
functions and they make their continuations, etc. In Scheme you 
have explicit access to the current continuation, and can pass it as 
a parameter to a function that you define. This is a good way to 
implement escaping from loops, blocks, and procedures, but can 
also be used to implement fancy control structures such as 
agendas in artificial intelligence applications. (I cannot tell a lie; 
the last sentence is a paraphrase of one found in 
MacScheme+Toolsmith’s excellent documentation.) 

MacScheme+Toolsmith offers a lot to wander through with 
their library files and files that define access to virtually all of 
Inside Macintosh. There’s multitasking support, access to 
machine code definitions for those tricky or time-consuming 
processes, and standalone application support. 
MacScheme+Toolsmith may have little in the way of user 
interface, but it is an excellent example of the elegance and 
simplicity of Scheme as a dialect of Lisp, and with its Inside 
Macintosh, multitasking, and machine code support, it packs a lot 
of power into a very small package. To top that off, they haven't 
forgotten the beginners out there: each copy of 
MacScheme+Toolsmith includes a copy of Dan Friedman and 
Matthias Felleisen’s The Little LISPer, Trade Edition, from The 
MIT Press. I consider this book to be the beginner’s platform for 
learning Lisp (although the trade edition, which eventually 
covers such things as the applicative-order Y-combinator and 
writing a Lisp interpreter in Lisp, does get well beyond the 
beginning stages). 

Scheme also enjoys great popularity in some academic 
computer-science circles, such as MIT and Stanford. 

Common Lisp isn’tas conceptually pure as Scheme, perhaps 
partly because it was designed by committee. It does, however, 
have a very broad and very rich background, having drawn on 
ideas from many other dialects of Lisp, including ZetaLisp (the 
dialect used on Symbolics workstations), MacLisp (developed at 
MIT for Project Mac—not Macintosh-related at all), InterLisp 
(found on some Xerox Lisp machines, among other places), and 
yes, including Scheme as well. 

Common Lisp is intended to be a good computational 
language, with support for everything up to and including com- 
plex numbers. In Allegro CL, support for BigNums seems quite 
speedy compared to MacScheme’s BigNum support, and Alle- 
gro uses the МС68881 (if one is present) for its floating-point 
calculations. 

Some data types and functions that Scheme lacks are present 
in Common Lisp. For example, support for sets is part of the 
Common Lisp standard, as will be seen in the sample code below. 

Common Lisp is being widely accepted, partially because it 
does cover so much intellectual turf, partially because there are 
many implementations of it available, and partially because a lot 
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of well-known people and companies in the industry had input on 
it (including some who are in somewhat bitter competition with 
each other, such as Symbolics, Inc. and LMI). 

To sort of highlight one or two of the differences between 
Scheme and Common Lisp, I’ve taken a program that was 
originally written in Scheme and translated it to Common Lisp so 
that we can look at them side-by-side. The program was 
originally written in MacScheme by André Marc van Meule- 
brouck, and is copyrighted by him. He generously posted it to the 
GEnie network for the rest of us Lispers to enjoy and learn from. 
Its purpose is, given a data structure that represents a maze as a 
list of lists of connected rooms, a starting room, and a destination 
room, to print the most efficient route(s) for getting from start to 
destination. Here’s the Scheme code: 


; Copyright (с) 1986 by Andre’ Marc van Meulebrouck. 
; All rights reserved worldwide. 
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(set! castle ‘(Ca х) (а 
(хо) (x 
(k 1) Gj 
(h d) (м 


c) (а d) (a o) (a h) (m 0) 
b) (b c) (d e) (e f) (f g) 
i) Ci h) Ci n) (n 1) (n h) 
h) (k j) (m phone))) 


(define (find-route structure start goal) 
(define (find-route-aux routes) 
(define (goal? routes goal) 
(member #! true 
(аррепдег 
(тарсаг (lambda (x) 
(cond ((member goal (last x2) 
(list #!true)) 
(else #!null))) 
routes)))) 
(def ine Cf ind-route-io x) 
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(сопа ((пи11? x) #! true) 
(else (display (саг x2) 
(newline) 
(find-route-io (cdr x))))) 
(define (goals-only routes goal) 
Cappender (тарсаг Clambda (x) 
(сопа (Cequal? (саг (last x)) goal) 


(list x2) 
(else 81011222 
routes))) 


(cond (Cnul1? routes) #!null) 
((nu11? (goal? routes goal)) 
(find-route-aux (rid-dead-ends 
(make-routes routes)))) 
(else (find-route-io Cgoals-only routes 
доа1))))) 
(def ine Cappender х) 
(сопа CCnu11? x) #lnull) 
Celse Cappend (саг x) 
(def ine (make-routes routes) 
(define Cmake-routes-aux route) 
(def ine (choices room) 
(def ine Cset-difference set] set2) 
Cappender (тарсаг (lambda (x) 
(cond ((member x set2) #!пи11) 
(else (list x)))) 
set1))) 
(define Cextricate x) 
(сопа ((пи11? x) 8111) 
((member (саг x) (cdr x)) 
Cextricate (cdr x))) 
Celse Cappend (1134 (саг x)) 
Cextricate (cdr x)))))) 
(set-difference (extricate Cappender (mapcer (lambda (x) 


Cappender (саг x)))))) 


(cond (Cequal? (car х) room) 


(cdr x)) 
(Cequal? Ccadr x) room) 
(list (саг x))) 
(else #!null))) 
structure))) route)) 
(appender (mapcar Clambda (x) 
(list Cappend route 
(list x)))) 
(choices (саг (last route)))))) 
Саррепдег (тарсаг (lambda (x) 
(make-routes-aux х)) 
routes))) 
(define (rid-dead-ends routes) 
Cappender (тарсаг (lambda (x) 
(сопа С(пи11? (саг (last x))) 
81!ny11) 
(else (list х)))) 
routes))) 
(def ine (last x) 
(сопа ((пи112 x) 81110 
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(else (list (саг (reverse х)))))) 
(cond CCor Catom? structure) 

(null? structure) 
(pair? start) 
(pair? goal)) 

81ny11) 

(Cequal? start goal) goal) 

(else Cf ind-route-aux (rid-dead-ends 


(make-routes (list (list start)))))))) 
There it is, in all its splendor. Notice the heavy use of 
implicit iteration via MAPCAR. Also notice the use of 
LAMBDA expressions to pass functions to MAPCAR on the 
fly, without the bother of defining them and assigning them to 
a symbol and whatnot. Also note that what the LAMBDA ex- 
pressions evaluate to is already a function ready to go to 


MAPCAR. No additional sugar is necessary. 


Here's my Common Lisp translation of the same code: 


; Copyright (с) 1986 by Andre’ Marc уап Meulebrouck. 
; All rights reserved worldwide. 
; Common Lisp translation by Paul F. Snivelu 
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c) (a d) (ао) (a h) (m 
b) (b c) (d e) (e f) (f 
i) Ci h) Ci n) (n 1) (n 
h) (k j) (m phone))) 


(defun find-route (structure start goal) 


(defun f ind-route-aux 


(routes) 


(defun goalp (routes goal) 
(member Т 
Cappender 
(тарсаг (function CLAMBDA (x) 
(cond CCmember goal (last x2) 
(list Т)) 
(T NIL222) 
routes)))) 
(defun find-route-io (x) 
(сопа ((null x) Т) 
CT Cprint (саг x)) 
(find-route-io (cdr х22222 
(defun goals-only (routes goal) 
Cappender (тарсаг (function CLAMBDA (x) 
(cond (Cequalp (саг 
(list x2) 
(T NIL)))) 
routes))) 


Clast x)) goal) 
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(сопа ((null routes) NIL) 
((пи11 Cgoalp routes goal)) 
(find-route-eux (rid-dead-ends 
(meke-routes routes)))) 
(T Cfind-route-io Cgoals-only routes 
goal))))) 
(деГип appender (x) 
(соға CCnull x) NIL) 
(Т Cappend (саг x) Cappender (cdr х)))))) 
(defun make-routes (routes) 
(defun make-routes-aux (route) 
(defun choices (room) 
(defun extricate (x) 
(сопа CCnull x) NIL) 
CCmember (саг x) (саг x22 
Cextricate Ccdr x22) 
(T (append (list (саг x2) 
(extricate (cdr х)))))) 
(set-difference (extricate Cappender (mapcar (function 
CLAMBDA (x) 
(сопа (Cequalp (саг xroom) 
(саг x22 
(Cequalp Ccadr х) room) 
(list (саг x22) 
(T NIL)))) 
structure))) route)) 
Cappender (mapcar (function (LAMBDA (x) 
(list (append route 
(list x))))) 
(choices (саг (last route)))))) 
Cappender (тарсаг (function CLAMBDA (x) 
(make-routes-aux x))) 
routes))) 
(defun rid-dead-ends (routes) 
(appender (mapcar (function CLAMBDA (x) 
(сопа ((null (саг (last x22) 
NIL) 
(T (list x))))) 
routes))) 
(сопа (Cor Catom structure) 
(null structure) 
(not (atom start)) 
(not (atom 081222 
NIL) 
CCequalp start goal) goal) 
(T (find-route-aux Crid-dead-ends 
(make-routes (list (list start)))))))) 


It looks much the same, doesn't it? If you look closely, 
you'll see a lot of minor syntactical differences, such as the use 
of “T” instead of “#!true.” More importantly, however, you'll 
notice that the definition of "set-difference" is missing, since 
Common Lisp already has it, and you'll notice the (function. ..)" 
around the LAMBDA expressions, because Common Lisp wants 
it that way. Also, there's no "pair?" in Common Lisp, so the 
question was “What is he really looking for?" and the answer was 
“Не wants to make sure that the start and destination are atoms." 
Hence the “(not (atom...))" lines near the end. 

Someone who is abit more of a *Common Lisp Rambo” than 
I am at the moment might think in terms of restructuring this 
program so that you can eliminate the definition of “appender” 
and replace the numerous “(appender (mapcar...))" invocations 
with “(тарсап...)” ones. Тһе problem with that is that 
*MAPCAN" is adestructive operator (one that performs surgery 
on lists, rather than copying them) that can exhibit some pretty 
weird side-effects if you aren't careful with it. The optimization 
is left as an exercise for the reader. 

Well, that wraps up this look at two excellent Lisp systems 
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for the Macintosh. I expect to see both of these products evolve 
over time. MacScheme has been evolving, and has become a 
product that we Scheme fans can really appreciate, especially 
with its good documentation, large amounts of source code to 
tinker with and learn from, and its support of the Toolbox, 
multitasking, machine code interfacing, and standalone applica- 
tions. 

Allegro CL is remarkable as the first full Common Lisp for 
any mass-marketed microcomputer, and for its extensive and 
powerful user interface. It also offers excellent Toolbox access 
and several interesting example programs, including color ex- 
amples and Cosell, a Common Lisp spreadsheet. The lion's share 
of the documentation is Common LISP : The Language, which in 
Common Lisp circles is referred to as “The Silver Bible." A сору 
is included with the product. Also included is a copy of Common 
LISP: The Index, by Coral's own Rosemary Simpson, which 
attempts to improve (and succeeds at improving) upon the index 
that is in the book. The remaining documentation is a somewhat 
terse description of Allegro CL specifics that would benefit from 
a less dry, “just the facts, ma'am," more lively style and from 
more examples. Issues remaining to be resolved are multi- 
tasking, interfaces to other languages, and standalone applica- 
tions. However, Coral has clearly positioned this product as 
being in line with the likes of Symbolics' work, especially with 
the introduction of Allegro Flavors and the promised support of 
CLOS and Common Windows. 

I'm lucky—I’ve got 'em both. Other folks might not be so 
lucky. If you're looking for a Lisp system, both are recom- 
mended highly, albeit for different reasons. Scheme fans, 
MacScheme+Toolsmith will let you do just about anything you 
want, up to and including creating a standalone application that 
you can then sell or give away or whatever royalty-free. 

If you use Common Lisp professionally and have been 
looking for a real Common Lisp for your Macintosh, Allegro CL 
is it. It’s 100% bona-fide genuine Common Lisp, not some little 
subset. Speaking of which, if you're looking for a good, inexpen- 
sive subset, keep your eyes on Coral, who are talking about doing 
“Coral Lisp,” a subset of Allegro CL, for about $100.00. In fact, 
it should be out by the time you read this. This sounds like it'll 
be a great entry-level system for the first-time Lisper. Maybe 
Coral will take a hint from Semantic Microsystems and bundle 
The Little LISPer with their introductory Lisp. 

MacScheme+Toolsmith 1.0 

$395.00 

Semantic Microsystems, Inc. 

4470 S.W. Hall, Suite 340 

Beaverton, ОК 97005 

(503) 643-4539 


Allegro CL 1.1 

$599.95 

Coral Software, Inc. 
Р.О. Box 307 
Cambridge, МА 02142 
Orders: (800) 521-1027 Sol 
Tech Support: (617) 547-2662 
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Learning Lisp 
Lisp Objects: Ford vs Chevy 


Didier Guillon is a former restaurant manager, currently in 
the fourth year of a Computer Science program at Grenoble 
University in France. He is a member of AAAI and works in 
artificial intelligence as a consultant at the Medical University 
of Grenoble' s department of BioStatistics. He is also president of 
Mac Alpes, a club of Macintosh developers in Grenoble and has 
been using the Mac for two years. 


Welcome to this new column. When first started Macintosh 
programming, MacTutor and the contributing editors were there 
and helped me since issue number one. Now I think it’s time to 
share with you the knowledge I gained with the “oldest new 
language". So welcome to symbolic computation... you have a 
problem? No, don't be frightened, I have been so pleased when 
I discovered ABC' s of C that I wanted to introduce you to the 
Lisp world in a gentle way. The technique I will use may 
sometimes be criticized by expert Lisp programmers...but do 
they remember their first steps? 

Today I will present the object idea with a very dumb 
example and "how to" on the Macintosh. MacApp and MPW 
Pascal are there to let us remember that object programming 
becomes a reality day after day. But, since Smalltalk, no other 
language than Common Lisp did it with better efficiency. 


My Kingdom for an Object 


But what is an object ? To the outside world, an object is an 
entity. But for us programmers, an object is some private memory 
with a set of operations. An object can be a number, a Square, a 
text editor. An object which is a square knows alotof information 
about itself: how to calculate the area of the Square, the center of 
the square... When we want the object ‘square’ to Carry out such 
a calculation, we send him a message (we say: to invoke). But we 
Just tell him which operation we want, not how to operate. (If he's 
smart, he already knows that!) 

When a set of objects represents the same kind of informa- 
tion, we implement a class with a data structure and the proce- 
dures that operate on this data structure. For example, a class 
implemented for a rectangle would know how a specific object, 
called an instance, would carry out the operation rectangular 
area. This instance has private variables called instance variables 
and the function that will operate on the instance of a particular 
class is call a method. We just defined in fact the fundamental 
concepts of object programming: data abstraction, information 
hiding (not to tell “how to") and generic operation. But all this is 
just theory, so let's start with our dumb example. We will use the 
ExperCommonLisp (ECL) from ExperTelligence™, who 
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Didier Guillon 
Grenoble, France 
MacTutor Vol. 4 No. 4 


: x-y 
Xy 


since the last review of this language in MacTutor, did a lot of 
improvement and removed many bugs. 

First, let's create a class for ‘cars’ (note: we wrote cars to 
avoid the "car" word which is a Lisp reserved word). 


(defclass Ccars object) 
CIVS (color ‘blue) 
(price 0222 


Defclass contains a list with the name of the call and the 
name of the superclass. In ECL all the classes come from a special 
class called object. In fact object is a root class from which all 
classes are derived. The IVS stands for instance variable and as 
we Saw previously, will manage to store the IVS in each instance. 
You note the quote before blue? In Lisp every elementary object, 
called an atom, is evaluated. This evaluation returns a function 
name or the value attached to this specific atom. So, to prevent 
evaluation, we “quote” the atom which becomes itself a value and 
is attached to the instance variable color. This ‘quoting’ is not 
necessary for anumeric value. Then we define the method (using 
defmethod followed by the name of the class and the name of the 
method itself): 


(defmethod (cars small) () 
(setq price 800) 
(format Т “A small саг is just fun for “a dollars."$^ price)) 


This method is doing two things: setting price to 800 with 
setq, a Lisp word which will not evaluate the following word, 
price, and sets its value to 800 (for Pascal programmers it’s an 
assignment). Then it prints a message (good old Fortran world 
!11). You are now able to trace by yourself what the second 
method does: 


(defmethod (cars race) () 
(setq color “red) 
(setq price 20000) 
(format Т “A wonderful race car whose color is 78.74” color)) 


Now we link up what we define to this first class: we compile 
and define an instance (we will represent the return value by ->): 


(setq mylcar (cars ‘new)) 
-> "CARS INSTANCE $5402341A) 


"mylcar" is the instance which holds a copy of the class 
‘cars’. Let's invoke the instance in various Ways: 


(му1саг 'race) 
-) À wonderful race car whose color is RED. 
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cars method : small 


method : buy a Ferrari 


instance : my 1 саг 


color blue 
price O 


Ferrari 


instance : | buy a ferrari 


a Speed 
price O 
color blue 


Fig. 1 Our cars example illustrates basic concepts 


(туісаг 'small) 
-) А small саг is just fun for 800 dollars. 


Cmyicar 'price) 
-) 800 


(mylcar ‘price 200) 
-) 200 | 


(ту1саг ‘price) 
-) 200 


We can see the graphic image of the object we define, 
including the next subclass we will create: 


Here is the subclass Ferrari: 


(defclass (Ferrari cars) 
(IVS a_speed)) 


(defmethod (cars buu-a-Ferrari) () 

(setq а_зреед 200) 

(self “race) 

(format T “But when you drive at “a miles... Whoo !!!!“#* 
a_speed ) ) 


Same as the ‘cars’ object, but note the “self” word which is 
used to invoke the method race from the method buy_a_ Ferrari. 
As previously, we can say: 


(setq I-buu-a-Ferrari (Ferrari “new)) 
-> "XFERRARI INSTANCE $540233АА› 


(I.buy-a.Ferrari 'buy-a-Ferreri) 
-) А wonderful rece саг whose color is RED. 
But when you drive at 200 miles... Whoo !!!! 


(I buu-a-Ferrari 'price) 
-) 20000 


(I buu-a-Ferrari *со1ог) 
-) RED 
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We can see easily that 
I buy a Ferrari inherits from its 
superclass ‘cars’ all the methods and 
instance variables. We will not cover 
here some other concepts like class 
variables, super.... 

So now that we have an idea on 
how objects live, we'll have a look at 
ECL. In ECL, the object idea has been 
expanded to the Macintosh Toolbox. 


Before going on to the Macintosh 
toolbox, we have a look at another 
object expression, metamethod. A 
metamethod is a procedure which is 
invoked by sending an appropriate 
message to a class. We explain met- 
amethod because on the Macintosh 
we create a NEW metamethod which 


sets upthe required data structure. When invoking a specific met- 
amethod, the instance of a particular class will have instance 
variables which will correlate (and with the same name) to the 
equivalent fields in the Pascal data structure. An example from 
QuickDraw: 


(setq yourRect (Rect ‘new 30 40 250 280)) 


We just created the instance call ‘yourRect’ with а set of 
parameters. If we send it a message, we can access these instance 
accessors by the same name as in the Pascal structure : top, left, 
bottom, right. 


CyourRect 'bottom) 
-) 250 


or change their value : 


(yourRect ‘left 60) 
-› 60 


We can also draw, calling Toolbox procedures with the 
instance 'yourRect' : 


(!PaintRect yourRect) 


Note that trap names are prefixed by an exclamation mark. 
We are now ready to start programming our first minimum shell 
in ECL... but that's for next month. 


For those interested in following me, and starting Lisp, I 
recommend the very nice and easy book of Touretzky “А Gentle 
Introduction to Symbolic Computation". For the others, obvi- 
ously, Lisp 2e by Winston is a must. I intend to present the next 
coming months various aspects of Lisp programming in Artifi- 
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ooTbox Objec 


AutoHandleTo 


Point 
Rect 
Pattern 
Fontinfo 
Cursor 
BitMap 


PenState 
serShk 


EventDialog 
Dialog Template 
Alert Template 

Into4Bit 

oFReply 

oFTypeList 

oerotaRec 


ParamBlockRec 


fileParam 
loParam 
volumParam 
controlParam 


oystemCreatedTo 


indow Record 
Dialog Record 


Polygon 

Region 

Picture 

TERec 

ControlRecord 
enu 


Picture 2 


Fig. 2 How Lisp accesses the toolbox 


cial Intelligence, but also use some special languages as OPS 5, 
SmallTalk, Humble, Prolog (or why not Nexpert, just to let us 


dream...). If you have any suggestions, please contact me : 


Didier Guillon 

8 Impasse Saint Jean 
38240 Meylan 
France. 


Ihe complete program : 


(defclass (cars object) 
CIVS (color 'blue) 
(price 0))) 


(defmethod (cars small) () 

(setq price 800) 

(format T "A small car is just fun for ^а dollars."$^ 
price)) 


(defmethod (cars race) () 
(setq color 'red) 
(setq price 20000) 


(format T "A wonderful race car whose color 
color)) 


is “a.“$” 
j EXEEEEREx amp eg FARK RARE EEE KEKE 


,(setq myicar (cars ‘new)) 

,"«CARS INSTANCE $540234 1A» 

;(ту1саг 'race) 

JA wonderful race car whose color is RED. 
,(mylcar 'small) 
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,^ small саг is just fun for 800 dollars. 
;(mylcar 'price) 

,800 

;(myicar “price 200) 

;200 

;Стуісаг 'price) 

,200 


,P**X*X**XX*Second С]Ә5$5Ж%ЖЖЖЖЖЖЖЖЖЖЖЖЖ 


(defclass (Ferrari cars) 
(1У5 a_speed)) 


(defmethod (Ferrari Биу_в_Реггаг1) С) 
(setq ә. speed 200) 
(self 'race) 
(format T "But when you drive at “a miles ... Whoo 


Шым а speed)) 


; FEXCEEXEXEXEx amp еж 222222255. 


,(setq I.buy.a.Ferrari (Ferrari ‘new)) 
j"«FERRARI INSTANCE $540233AA» 


;KI-buy-a.Ferreri 'buy.a. Ferrari) 
;А wonderful rece car whose color is RED. 
;But when you drive at 200 miles... Whoo !!!! 


;(I-buy-a.Ferrari 'price) 
,20000 


;(I1-buy-a.Ferreri ‘color) 
;RED 
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HyperChat™ 
New HyperCard Products 


Fred Stauder 
Contributing Editor 


HyperCard MacTutor Vol. 4 No. 5 
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HyperChat is a new section of MacTutor which will bring 
you new hypertalk programming techniques and lead you into 
the realm of “User Friendly Programming". 

Each month weaim to inform you of the latest developments 
in the Hypercard Community, such as new products, ScriptTips, 
XCMD'Ss and Articles. I am sure you will enjoy HyperChat as 
much as we enjoy bringing it to you. 

Is Hyperware Vaporware? 

At the introduction of Hypercard there was much enthusi- 
asm from the Mac Community, also an outcry from the develop- 
ers who saw some of their plans dissrupted. What was Apple 
trying to do? Is this system software? Did people scream out 
when MPW was introduced? Of course not, it was a tool to be 
used by developers. Apple has positioned Hypercard the same 
way, аз a tool. There is а difference though in that Hypercard is 
the tool “for the rest of us". 

Are you having a DejaVu? A lot of people laughed at the 
Mac when it was introduced. How can this toy do real comput- 
ing? How сап you do areal application with Hypercard? Now we 
have seen an explosion of Stacks for Hypercard. Take a look at 
them; a good proportion are garbage. Look at many of the early 
programs on the Mac, were they not also garbage? I believe it is 
only a "teething"problem. Now take a look at two professional 
programs written in Hypertalk, Buisness Class, and Focal point. 
There is a market for Professional Hypercard Stacks, there is no 
market for garbage. The sales of these stacks has been remark- 
able. People are finding them very productive to use in their daily 
lives. Hypertalk is not a passing phase, just as the Mac wasn't, it 
will continue to evolve and grow. Why should programmers be 
scared of this new thing? Hypercard will give you more oppotu- 
nities, it will allow you to do some “look and feel" tests before 
you write code. You can also do quick jobs that would just take 
too much time to write in another way for them to be economical. 
It is also very useful to doccument and spec out projects. A 
famous Australian expression is; *you'll never know unless you 
“ауа go". 

If you think it too beneath you to program in Hypertalk look 
at the people who use it, including Bill Atkinson the visionary 
who wrote Hypercard. Many of us are caught up in the invest- 
ment time it takes to learn a language, so to go to another one we 
регсіеуе as a loss. Our aim should be to hack concepts and ideas 
instead of syntax. 


Hypercard at MacWorld: San Fransisco 

Hypercard made its commercial debut at Mac World, with 
the introduction of dozens of commercial stacks, books and 
publications. 

One of the hilites of the show was seeing Bill Atkinson 
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demonstrate Hypercard. It was such a joy to watch the audience 
come alive with such enthusiasm. Bill was lucky though because 
he had the help of the youngest HyperHacker, his daughter Laura 
(you probably have seen her digitised photo in the slide show 
Stack that came with Hypercard). 

Laura would yell out the command keys to her dad to make 
him get to the good bits faster. 

After Bill's talk I spoke with Amanda Goodenough who 
wrote “Inigo Gets Out”, “Inigo Takes a Bath", and “Your 
Faithful Camel"(for those of you who have not seen them these 
are a great example of childrens stacks). Amanda told me how 
young kids are taking to Hypercard. Using their active imagina- 
tions and the multi dimensions of Hypercard to create wonderful 
things. [One of the best ways to test your software is to let 
children try it. They will quickly point out conceptual inconsis- 
tancies.] 

Later on Laura Atkinson was using a MacRecorder to input 
sound into Hypercard. It was such a joy to see a young child 
doing, without much assistance, what MIS managers with their 
multi million dollar computers, can’t do. 

A lot of people were talking about the limitations of Hyper- 


_ card. Well I suppose everyone has forgotten that Apple did listen 


to the users about the limitations of the Mac. 

I think the Mac II is a good response to people’s needs. My 
advice is good products take time; be patient. 

There were too many things to mention them all so I will give 
examples of what I feel are the most innovative. 

Focal Point and Buisness Class 

If you haven’t seen these stacks; you should. Danny 
Goodman did a remarkable job developing these stacks during 
the time of quite a few revisons of Hypercard. I won’t go into 
details, but I would like to point out that these professinal stacks 
made a big impact at MacWorld SF. 


" é File Edit Go Tools Objects ` 


ШЕ 


г 4 m 1 h 
+ 

Е HHL 

11392214424 НЕЕ иш fü E T Hi 


ept & Progremming by Danny 
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MacRecorder 
Farallon has released the MacRecorder with two programs, 
SoundEdit and HyperSound. These two programs are very good 
examples of what should be done to make a good interface; clean, 
simple, and a pleasure to use. Written by Steve Capps and the 
Farallon team. HyperSound lets you record a sound and place it 
directly into a stack, ready to play. (see HyperTests) 


The MacRecorder™ 


i 
ЗВ 
i «d 
ИЙНИН M 
РН qot 


- zRecording іп 
speed: stereo 


Tempo ll 
This new version of Tempo is a much more powerful version 
of the original. 


With an XCMD called PostEvent written by Dewi Williams 
you can call a Tempo II macro directly from hypercard, run the 
macro, and return control to hypercard. This allows you to 
automate things that you always wanted to do. Such as issuing 
click commands for dialog boxes. Hypertalk won't allow you to 
invoke desk accessory menu items via doMenu. This can be done 
now with a simple macro. 


PostEvent can also be used with Quickeys. 
" é File Edit Go Tools Objects Utilities Compass 


Hypercard, QuicKeys & Tempo 


This steck explains how to glue together Hypercerd with the Tempo macro utility or 
the QuicKeys keyboerd enhencer , using в ХСМО resource celled PostEvent. 


You'll need Tempo version 1.2 or QuicKeus 1.0, end System 4.1 or later. Start by 


extrecting PostEvent from this stack with ResEdit or the Resource Copier end copying 
it to your Home Steck. 


There ere no demonstrations of macros being invoked built into this stack - it's too 
evkwerd to have to install the macros first, and there can be screen size problems. 


e Click here for suggested uses 

e Click here for Tempo end Hypercerd 

e Click here for QuicKeys end Hypercerd 

e Click here if you use both Tempo end QuicKeys 


This stack end its XCMD resource із public domain, from Dewi Williams. 
Delphi: DEWI. (303) 443 9038. 


49 % 
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Bright Star 
Some people may have missed this item at Mac World Expo 
in SF and if you did it is a pity. 
Itis based on Bright Star Technology’s real Time Animation 
and Vivification Engine, the RAVE, and it's RAVEL language. 
It drives a face in Hypercard that will mouth the words from 
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ASCII text, and simultaneously speak the text. The power of this 
language is amazing. The images are digitized (the one in the 
figure is of yours truely) with a video camera. 

The number of images used for the phonemes can be as few 
as 5 images or for greater precision 50 or more. Ravel allows 
color images as well, and is language independent. For example 
if you can have French text typed in and you will see your face 
move to French words. Bright Star have produced some applica- 
tions for teaching purposes. The potential of such technology 
holds a bright future for Bright Star. 
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Bright Star Technology says it best! 
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Hottest Development Stack 


Developer Stack 1.1, written by Steve Drazga, contains, 
XCMD's, XFCN's, Scripts, and a bunch of other goodies. It is 
designed to be a resource for Hypercard development. The 
interface is very clean and not cluttered like some other Hyper- 
card Development tools (In most cases when you design Stacks; 
more is not better). Steve is developing an upgrade stack that will 
update the Developer Stack. This Stack is available on most 
Bulletin Boards and from user groups. 


Developer Stack 


Issue Number 1.ir eeePOVER USER TIPSeee 


Issue Date 1/5/87 


This stack is free, and may be re-distributed 
in its original form with all original messages. 
It may not be sold commercially. К ts 
intended for educational & training purposes 
only and no warranty is made as to the 
suitablity of anything included in this stack for 
any specific purpose. 


xŠ 


To go to the beginning of a specific section Tu 
(XFCNs, Scripts, etc.) hold down the dg 
command key when clicking on the button. Biz: 


When you see an item in a field followed by 
an asterisk * , double clicking on that word 
will either give you more information, or [її 
take you to a linked card. ЗИ 


buttons" 
Stack Size 
Wasted 112256 | 


m Е 
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XCMDS Functions Scripts Buttons Quick Ref 
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Most Useful XCMD 
ResCopy written by Apple's XCMD Guru Steve Maller is a 
utility that allows you to copy resources from one file to another 
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directly through a dialog box or by using scripts. 

ResCopy works in a similar fashion to the Font/DA mover. 
You call install ResCopy into your home stack typing ResCopy 
into the message box brings up a window (see figure 6). You can 
copy, remove, rename, renumber resources, and play sounds. 
One really useful feature will allow you to convert different snd 
resources to Hypercard format. 

ResCopy allows direct resource copying from scripts. This 
is useful, for example, if you want to install a cursor or other 
resource into the Home Stack. The copying takes the form: 

ResCopy fromFile, toFile, *XCMD", 10000. 

This XCMD is a must for Hypercard developers. 


" é Fite Edit 


3383849888: 


VNUM 910000 "Version info" 

i| | XFCN 9913 “FileName” 

#1 | DLOG 910000 "ResCopy" 

Я | DLOG *10001 "RC Help" 
DITL 910001 "RC Help" 

|| | DITL 910000 "ResCopy" 

j| | ХСМО 910000 "ResCopy " 

Ч | ICON 928292 “Lil” Button” 
ICON 9150686 "Andrea 1" 


snd 9679 "Oops" 

XFCN 9913 "FileName" 
XFCN 9602 “DeleteMenu” 
XFCN *600 "NewMenu" 
XFCN 90 "NewFileName" 
XFCN 9113 "FileModDate" 
XFCN 9111 "MovefFile" 
XFCN 9105 "RenameF ile" 
XFCN 9545 "DeleteFile" 


: ResCopy 4.0514 ' File: 
: AJS-SE Volume: 
1 Free: 3493K Free: 3493K 
| Selected: 128 bytes Selected: 


Version 4.0514 9-Мағ-88 


Developer Stack 1.1 
^J8-SE 


P9990 90000000809 000000000000 09000000000000900909000000006 002009044. 


|| € Apple Computer , inc. 1908 
| by Steve Maller 


—ScriptTips 

The first ScriptTip allows you to edit the script of a stack, 
Background, Card, Field, or Button. You can put this script into 
the Home Stack so it can be used in all stacks. To edit a button or 
a field hold the mouse button down over a field then move the 
mouse up with the button still depressed. The script editor will 
then be envoked. To edit a stack script choose part of the card that 
does not have any buttons or fields then move the mouse to the 
top of the card, (or past itif you havea large screen) while holding 
down the mouse button. To edit the background script, move to 
the left of the card with the mouse button down, and to edit the 
card script move right. I have found it helps when you are 
debugging and it will work in most stacks. 


AutoScriptEdit by Fred Stauder 


- Put this Script into your Home Stack 

- To use keep mouse down over Button or Field and move mouse 
Up 

- To edit Bkground Script keep mouse down - move to very left 
of card 

- Card Script - move right 

- Stack Script - move up 


on mousestilldown 
set cursor to 4 
put char 6 of the target into C6 
if C6 is quote then AutoScriptEdit 
if Сб is 41” then AutoScriptEdit 
if Сб is quote then exit mousestilldown 
if C6 is “i? then exit mousestilldown 
if the mouseV <item 2 of rect of target then edit script of 
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target 
end mousestilldown 


on AutoScriptEdit 
if the mouseH < 2 then edit script of this bkgnd 
if the mouseH › 510 then edit script of this card 
if the mouseV < 2 then edit script of this stack 
end AutoScriptEdit 


- Non-Comercial use only - A11 Rights Reserved 


- Fred Stauder, Hypercard Editor, CHyperChat) MacTutor March 
1988 


This second ScriptTip is a convenient method to bypass a 
card that is not normally important for everyday use, such as an 
about card. Itis also a good place to hold information that the user 
does not have to see. You can easily set a flag to access the card 
when you want to get information from it. 


HideCard by Fred Stauder 
- This script allows you to “hide? cards 

- For example әп about box card 

- It does not completely hide the card it just passes it 
— Put it in to the Card Script 


on opencard 
if the optionkey is down then exit opencard 
- put in апу type of flag eg: 
- if FlagUnLock is true then exit opencard 
if the number of this card >the number of recent card ~ 
then go to next card 
if the number of this card «the number of recent card - 
then go to previous card 
end opencard 


- Non-Comercial use only - A11 Rights Reserved 
- Fred Stauder, Hypercard Editor, (HyperChat) MacTutor March 
88 


—HyperTest 


Farallon's 
MacRecorder, HyperSound, and SoundEdit 


The MacRecorder is a sound digitizer that is slightly larger 
than a mouse. it draws is's power from the serial port, so there is 
no power supply needed. It has a built in microphone, mic jack, 
ine jack, and volume control. Using two units you can record in 
stereo. Beeps sound incredible going from one speaker to the 
other. The MacRecorder is packaged in a handy bookshelf box 
containing, a MacRecorder, cables, a great manual which in- 
cludes theory of sound, and three disks. 

Hypersound is a hypercard stack that looks like a tape 
recorder and best of all acts like one it is a very simple stack and 
a good example of a clean interface. (see figure 7 next page) 

First you check the input level and adjust the volume control 
on the recorder. Then all you have to do is hit the record button 
and the sound will be recorded as a “snd “ resource. There is а 
button that allows you to copy the sound to a stack. You choose 
the stack, the snd is copied and a button is created that plays the 
sound. There is a button that launches the second program of the 
package; SoundEdit. 
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HyperSound™ € 
(SOUND. 


Bn ü i 


Copy Sound to Stack SoundEdit™ 


Sample Rote 
@ 22 KHz 
ОП KHz 
Q? KHz 


O 5 KHz 


Rec ІР Erase 
НЕМЕНЕ 
Fig. 7 HyperSoun d 


Create Home Button 


SoundEdit allows you to edit sounds in a very natural 
manner(see figure 8), such as copy and paste if you have a color 
monitor you can take advantage of it by coloring particular bits 
of the sound waveform. 


é File Edit Settings Play Effects Window 


ШШЩ ШШЩ ШШШ 
h qm (108461 12592] | 
нн «> | 


There are many different effects from echo, to a graphic 
equaliser filter. Naturally youcanrecord with SoundEdit and you 
can store sounds in many forms as well as hypercard, including, 
VideoWorks, JamSession, and StudioSession. 

Farallon pioneered the use of Hypercard to demonstrate 
products. They developed a stack called “Тһе PhoneNet Demo 
Stack" which is an interactive stack wich uses sound to hilite the 


ettings Play Effects Windows 


SoundEdit™ lets you record, edit and mix your sounds 
to create tracks for your favorite programs including 
HyperCard™, VideoWorks™, JamSession™, апа 
StudioSession™ 


| semet bd dno papanne Pre | 
| TURA li ШІ С 
Қ (12352) АСК 
неч [ 90926] <> ( 271291] 57122) 


demo. Developers are now seeing the merit in putting help stacks 
with their products, and also using Hypercard to Demo some of 
the product functionality without releasing a crippled demo 
version. This way you can guide your audience to the features 
without them having to blindly explore on their own. 

Two other stacks are included in the MacRecorder package 
one is called MacRecorder which is a guide and includes some 
good sound examples. 

The second is a stack called MacRecorder Applications and 
this shows examples of applications that can be made with sound. 
A good example is a face and as you click on parts of the face, up 
comes the name in English and French and you here the French 
word Spoken. Don't get your hopes up too high, nobody yet, has 
written a script that will allow you to speak into a MacRecorder 
in English and have the sound come out in French. 

If you are planning on doing any serious Hypercard devel- 
opment I would recommend the MacRecorder package from 
Farallon it is one of the most professional packages I have seen 
and at under $200 it is great value. 

Please send your ScriptTips, Stacks, HyperArticles, Com- 
ments, and Ideas to: 

Applelink D0280 for fastest turnaround or 

Fred Stauder 

Ecofin Research and Consulting 

Lavaterstrasse 45 

Zurich 8002 Switzerland 

or to the MacTutor office. 227) 
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HyperChat™ 
PopUpMenus in HyperTalk 


Hy perCard 


Joseph Bergin, Professor 
Marist College, NY 
МасТшог Vol. 4 No. 5 


S 


When Hypercard first appeared it wasn’t possible to include 
user defined menus in your stacks. While waiting for my 
Hypercard developers kit to arrive from APDA I decided to 
experiment and to see what could be done without resorting to 
XFCN's and XCMD’s. The result of my early trials is shown іп 
Figure 1. It looks similar to a menu bar except that I placed it on 
the top of a "card" instead. of the top of the window. Actually 
what you see is a collection of invisible labeled buttons drawn 
across the top of a card and not an actual menu bar. 

In Smalltalk a popup menu is a menu selection device which 
appears (pops up) when you click the mouse button on certain 
screen areas. These areas do not need to be anywhere special, and 
they do not need to be labeled. You select an option by clicking 
(not releasing) on one of the choices. For example the main 
control window pops up when you click on the background 
outside of any window. Another difference between Apple’s pull 
down menus and Smalltalk's popups is the fact that popups may 
Stay on the desktop while you work until you actually dismiss 
them, usually by taking some menu choice. This is similar to 
Apple’s new tear off menus that made their appearance in 
Hypercard. 
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When you click on one of these buttons a “Popup Menu” 
appears. If we click on the “Apple” we get Figure 2. This popup 
is actually a field. Clicking on the Apple only made itappear. As 
you can see it has four choices presented to the user. If the user 
clicks on one of these the corresponding action will be taken and 
the popup will disappear. If you don't take an action the popup 
will just sit there while you do other things. The popup will also 
disappear if you move the browser (cursor) into the window and 
then move it out again withoutclicking. This just “dismisses” the 
popup. 
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Fig. 2 The HyperCard PopUpMenu 


The purpose of popup menus is to provide for those situ- 
ations in which you want to provide a lot of options for your user 
but you don't want to clutter up the cards and/or backgrounds 
with a lot of buttons which add visual “noise” to the interface. 
The options may be clustered together in groups and each group 
may be provided with a single button to call up a popup with the 
associated choices. There are a number of other solutions to this 
problem but if used wisely popup menus can be a valuable 
addition to your Hypercard toolkit. 

Actually, what I learned about HyperTalk along the way to 
creating these popups was as valuable as the popups themselves. 
In order to make the creation of popups easier I decided to 
automate the process. This made it unnecessary for me to 
remember all of the steps that were needed in creation of a popup 
and its associated button, field, and scripts. The solution was to 
create a command which creates new popups, but it does so by 
having a script that writes scripts. 

In the Unix world a program which writes other programs is 
a fairly standard item (Y ACC and LEX for example) but they 
seem to be less used in other environments. They are ап 
important development tool, however, and quite easy to do in 
Hypercard. 


The necessary scripts 


Before we get into the operation of the ScriptWriter we 
should look first at the scripts that are needed for the popups to 
operate correctly. 

Suppose that we want to have a popup called “Apple” and we 
want it to look like the first example in this article. We will need 
a background button called “Apple” which, when clicked shows 
a background field called “Apple.” The script to do this is simply 
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on mouseUp 
show bkgnd field Apple - at the clickLoc 
— remove the dashes above for a 
-nice effect 


end mouseUp 
which belongs in the script of the "apple" button. 


Next we need the background field called by the same name, 
“Apple.” Ithas а script to hide itself (target) and one to select and 
execute the required user choice, which here is done on 
mouseUp. It also has a special action command (“арр!е1”, 
“apple2”, etc.) for each visible line of the field. You may have 
more action commands than visible lines if you like but they 
won'tbe usable. You can also add new action commands at any 
time by editing the script, and increasing the number of visible 
lines in the field and all will be well. Note though that the 
lockText property of the field will have to be set to true so that 
Hypercard will be able to recognize a click in the field. The 
required scripts for this field are: 


on mouseLeave 
hide the target 
end mouseLeave 


on mouseUp 
selectChoice 
end mouseUp 


on epplel 
open MacWrite 
end apple! 


on epple2 
open MacPaint 
end apple2 


on apple3 
open MacProject 
end &pple3 


on apple4 
doMenu “Quit Hypercard" 
end apple4 


Recall that the second choice on the “Apple menu" was 10 
open Mac Paint. This will happen when we execute the com- 
mand apple2. The command selectChoice decides that the 
mouseup happened on line 2 of the popup and dispatched the 
command apple2. 

The small scripts appleN can contain anything that you like. 
They can show or hide fields or buttons. They can paint. They 
can do menu commands or open files or stacks. They should be 
kept short, though, perhaps by defining new commands that they 
call. 

After the field was created and the scripts put into it the 
lockText was set to false so that its contents could be edited. Then 
a line was entered into the field for each possible choice, 
indicating what the choice is. Then the lockText was set to true. 

The script for selectChoice is either in the stack script or, 
perhaps, in the script of the Home Card. This command is called 
when the user mouses down in a popup. It first computes the line 
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number on which the user clicked the mouse and then executes 
a command whose name is the same as the name of the field 
which took the click with the line number appended to it. Thus, 
if the user clicked on line 3 (selection 3) of a popup whose field 
was called Apple, this script would execute command apple3, 
which was shown above. 


on selectChoice -used by popups 
put the short name of the target into theName 
get the rect of the target -field clicked іп 
put item 2 of it into top -top of the rect 
get the textHeight of the target 
put it into size -how big each line is 
put CCitem 2 of the clickLoc) - top + size) ^ 

div size into lineNumber 

send ( theNeme&linenumber) to target 
— executes the required command 

end selectChoice 


How to create popups 

Since there is so much to do and type for popups it would be 
nice to automate their creation. The following shows how. It 
assumes that you want your popup buttons and fields that define 
the popup to be part of the background, and that if you create a 
new card from the background you will want the popup to look 
and behave the same in the new card. None of these assumptions 
are required and you might experiment to discover the effect of 
doing it differently. That would require modifying the script for 
the command *newPopup" which is described next. 

To create a new popup called Apple, with four options, in a 
stack that contains all of these scripts you just type 


newPopup Apple,4 


into the message window and the button and field will be 
created and the required scripts will be put into them. You will 
then need to resize and place the field in the card, type your menu 
options into it, lock its text, and edit the action commands to give 
the effect that you want. The action command skeletons- 


on Арр1е1 


end Арр1е1 
etc. will be created for you however. 


The script that does all this work is shown below. It uses 
three other commands which are shown later. First, newPopup, 
which has two parameters, theName and theNumber, locks the 
screen to speed things up, says that we want to do this stuff to the 
background, and remembers the current tool so that it can be 
restored to the user at the end. Next it calls the first auxiliary 
command to create the button which will bring up the popup. 
Then the next command creates the popup itself, and the last 
command in the group adds a script segment to the background 
so that new Card operations will perform as suggested above. 
Finally the user's state is restored and the screen unlocked. [I 
have done some modifications to the script which will allow a 
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windoid type menu that can be draged around. The original script 
is intact; there arecomments how to modify it. The modifications 
are in italics. -HyperEd] 


on newPopup theName, theNumber 
— add next line for watch cursor НурегЕа 
- бей cursor to 4 


set lockScreen to true 
set editBkgnd to true 
put the tool into 0147001 


doNewButton theName 


— edd this line HyperEd 
- doNewBtnClose theName 


doNewF ield theName, theNumber 
set editBkgnd to false 
fixBkgnd theName 


choose 0107001 
set lockscreen to false 


— Return to normal cursor HyperEd 
- set cursor to 1 


end newPopup 


[The next section puts in the button for the close box. 
HyperEd] 


-on doNewBtnClose theName 
— set editBkgnd to true 
doMenu “New Button” 

set name of bkgnd button “New Button” to “close” 

set style of bkgnd button close to checkbox 

set autoHilite of bkgnd button close to true 

set showname of bkgnd button close to false 

set rect of bkgnd button close to 206, 73, 226,90 

put “оп mouseup^ into newScr ipt 

put “hide bkgnd field” && theName into line 2 of newScr ipt 
put “hide bkgnd btn close” into line 3 of newScript 

put "set hilite of me to false” into line 4 of newScr ipt 
put "set hilite of bkgnd btn” && theName && “to false” ^ 
into line 5 of newScr ipt 

put “end mouseUp^ into line 6 of newScript 

set script of bkgnd button close to newScr ipt 

-end doNewBtnClose 


- This whole procedure HyperEd 


Next we need to examine the three auxiliary commands that 
newPopup used. The doNewButton command is the easiest and 
itillustrates the technique of scripts which write scripts. The first 
line of it just creates a new button. It doesn't say background 
button, but it will be because of the fact that it is called after 
setting edit bkgnd to true. The next five commands just set some 
properties of the new button to something convenient. Note that 
the New Button menu command should set the new button's 
name to New Button. If it doesn't, you will need a script called 
newButton which just sets the name of “the target" to “New 
Button". We will need to do a similar thing for new fields also. 
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on doNewButton theName 
- set editBkgnd to true 
doMenu “New Button" 
set name of bkgnd button "New Button^ to theName 


— change next line to shadow HyperEd 
set style of bkgnd button theName to transparent 


— chenge next line to false HyperEd 
set autoHilite of bkgnd button theName to true 


set showname of bkgnd button theName to true 

set rect of bkgnd button theName to 206,70, 306,92 

put "оп mouseup^ into newScript 

put “show bkgnd field^ && theName into line 2 of newScript 


— add these three lines HyperEd 

- put “show bkgnd btn close” into line 3 of newScr ipt 

- put “set hilite of Жопа btn” && theName && "to true” 
- into line 4 of newScr ipt 


put “end mouseUp" into line 5 of newScript 


-- This Section added take away “-” HuyperEd 

- put “on mousestilldown" into line 8 of newScript 

- put “set lockscreen to true” into line 9 of newScript 

- put “if the visible of bkgnd field” && theName && “is true 
then” 7 

- into line 10 of newScript 

- put “set the loc of me to the mouseloc” into line 11 of 
newScr ipt 

- put "set the loc of bkgnd btn close to the mouseh -36, 
the тоивеу” - 

- into line 12 of newScript 

- put “set (һе loc of bkgnd field?” && theName && “to the 
mouseh, the mousev*93^*4 

- into line 13 of newScr ipt 

- put “end if” into line 14 of newScr ipt 

- put “set lockscreen to false?” into line 15 of newScript 

- put “end mousestilldown* into line 16 of newScript 

— End Section HyperEd 


set script of bkgnd button theName to newScript 


— added HyperEd 
- set hilite of bkgnd btn theName to true 


end doNewButton 


[These sections ad the script neccessary to move the Drag- 
Menu. HyperEd] 


The next four commands write a script into the new button. 
Suppose that the user had originally typed newPopup Apple, 4 
into the message window. Then theName is Apple, and theNum- 
ber willbe 4. After we execute the first of these script writing 
commands the local variable newScript has a value: 

newScript- 

on mouseUp 

Then after the second we will have: 

newScript- 
on mouseUp 
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show bkgnd field Apple 


Note that && concatenates strings but leaves appropriate 
spaces between words. We could easily modify this to show the 
bkgnd field at the location of the users click. we would just insert 

&& "at the clickLoc" 

after the word theName in the second put command. After 
the next command our script is: 

newScript- 

on mouseUp 
show bkgnd field Apple 
end mouseUp 

The fourth command copies this to the script of our new 
button, whose name by now is “Apple” which is the value stored 
in theName. 

The next auxiliary script, doNewField, is a bit more elabo- 
rate but not much harder. It needs to know both the name and the 
number of action commands as these will be written into the 
script of the field. Again we simply create the field with the 
doMenu command and then set some of its properties to useful 
values. The next seven commands then write the mouseUp 
command for the field. It is left in local variable newScript, as 
before. After further augmentation we will put it into the script 
of the field. That will come at the end, just before we end this 
method. 


on doNewField theName, theNumber 
-set editBkgnd to true 
doMenu "New Field" 
set name of bkgnd field “Мен Field? to theName 
set showlines of bkgnd field theName to true 


set style of bkgnd field theName to shadow 


set textFont of bkgnd field theName to Chicago 
set textSize of bkgnd field theName to 12 


— This line added HyperEd 
- set the rect of bkgnd field theName to 206, 93, 396, 256 


— Remove the next four lines HyperEd 

put “оп mouseleave^ into newScript = 
put “hide the target” into line 2 of newScript - 
put “end mouseleave” into line 3 of newScript 
put * * into line 4 of newScr ipt = 


put “on mouseUp” into line 5 of newScript 
put “selectChoice” into line 6 of newScript 
put “end mouseUp” into line 7 of newScript 


repeat with x = 1 to theNumber 
put * 4 into line (8 + (x-1) * 4) of newscript 
put “on” && theName&x into line (9 + (x-1) х 4) of 
newScr ipt 
put ^ “ into line (10 + (x-1) * 4) of newScript 
put “end” && theNeme&x into line (11+ (x-1) * 4) of 
newscr ipt 
end repeat 


set script of bkgnd field theNeme to newScript 
end doNewF ield 
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The only new feature here is the repeat command which 
writes the action command skeletons onto the end of newScript. 
Note that at this point newScript has seven lines. Each time that 
the loop body is executed we put four more lines into the script. 


The first line is blank. The next will say, for our example, 
on Applet 


or “Арріе2...” 

depending on the value of x which will vary between 1 and 
theNumber. This numeric value is appended to theName. The 
third line is blank again and the fourth gives the end line for the 
script. Finally we stuff newScript into the field script and quit. 

Both of the above scripts were simple in that we were starting 
fresh with a new object and were writing complete scripts. The 
last script in this group writes a script segment into the newCard 
method of the background script for the current background. It 
assumes that if the background has such a method then it contains 
a line somewhere with nothing on it but the comment: 

—here— 


The modification will be done just above this line. If your 
background script doesn’t have a newCard method at all then all 


is well and this script will create one with the required comment 
line. 


on fixBkgnd theName 
get script of bkgnd 
put it into bgscript 
put the number of lines of it into numLines 
put “no” into found 
repeat with x = 1 to numLines 
get line x of bgscript 
if it contains "-here-^ then 
put “yes” into found 
put x into where 
exit repeat 
- got it 
end if 
end repeat 
get the number of this background 
put it into bknum 
if found = “no” then 
put return & “on newCard “ && return ~ 
efter lest line of bgscript 
put return after last line of bgscript 
put “set lockScreen to true” & return ^ 
after last line of bgscript 
put “push сага” & return after last line ^ 
of bgscript 
put “go to recent сага” & return after ~ 
last line of bgscript 
put “get bkgnd field” && theNeme & return ^ 
after last line of bgscript 
put “рор card^ & return after lest line of ^ 
bgscript 
put “put it into bkgnd field” && theName & ~ 
return after lest line of bgscript 
put *-here-^ & return after last line ^ 
of bgscript 
put “set lockScreen to false” & return ^ 
after last line of bgscript 
put “end newCard^ & return ~ 
after last line of bgscript 
else 
put "push card” & return before ^ 
line where of bgscript 
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put “go to recent сага” & return before - 
line where *1 of bgscript 
put “get bkgnd field” && theName & return ~ 
before line where *2 of bgscript 
put “pop card” & return before ~ 
line where +3 of bgscript 
put “put it into bkgnd field” && theName ~ 
& return before line where *4 of bgscript 
end if 
set script of background bknum to bgscript 
end fixBkgnd 


The first few lines of this script search for the magic 
comment —here— in the script. If it is not found a newCard 
method with all the required parts is written into the background 
scriptcopy whichisnow storedin the local variable bgscript. Not 
much new here, except that we are appending to an existing script 
which explains why we include the “returns” at the beginning of 
various put commands. If the comment was found on line 
"where" then the required script is inserted just before it. The key 
part of the script that we write into the variable bgscript, for later 
stuffing into the background script itself, is justa way to copy the 
contents of the popup field from the original card into the field for 
the new card. This will make the popup menu have the same 
choices as the original card had. We must first go back to the 
original card, copy the field contents, go back to the new card and 
then put the contents into the old bkgnd field but from the new 
card. This requires writing a sequence push-go-get-pop-put into 
the background script each time we create a new popup, so that 
the field will get copied each time we create a new card. Simple. 
Except that the line counting gets a little tricky in modifying the 
scriptas we are repeatedly modifying it and changing linecounts. 

Anyway, in spite of the complication of the scripts, the use 
1$ quite simple. Just type newPopup “зотеМате”, *someNum- 
ber" into the message window and a new popup will appear in 
your stack as if by magic. 

You can also refine your popups nicely by modifying the 
scripts slightly. For example, you might want to have a popup 
which has different choices in it at different times, or shows the 
choices in different ways. Here is a script (from the Home Card 
or the stack script) which puts a check mark at the beginning of 
aline of a popup. Just remember that lines count between actual 
"returns" in Hypercard. Auto wrap lines don't count. Call this 
from your action command scripts 


on wantCheck fieldName, lineNumber 
- toggles а checkmark at the beginning of а 
- line of a bkgnd field 
get line linenumber of bkgnd field fieldName 
if cher 1 of it © “м^ then 
Put “wv” before it 
else 
delete first cher of it 
end if 
put it into line linenumber of L 
bkgnd field fieldName 
end wantCheck 


Interface guidelines 
Popup menus that look like ordinary menus but which 
behave differently will not be admired by your users. They will 
be expecting “Press-drag-release” to choose, and if they need to 
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"click-move-click" instead it will only add to their frustration. 
The solution is to make them look different. That is to say, the 
buttons which summon the popups should not be arranged in the 
form of the first card shown in this article, all in a row across the 
top of the window. Words down the left might be OK. Icons 
instead of words would probably be acceptable. One of the best 
methods is tocover partof your background with a large invisible 
button which has an invisible name as well. Stack instructions 
(perhaps summoned by a button press) could explain that options 
may be chosen by first "clicking near the upper left of the card." 
If nothing else is in front of your invisible button (or even if it is 
painted over by card graphics) your popup will be appear. One 
of the stacks that I recently built is a multi window editor that is 
controlled by popups. The next figure is the screen you see when 
the stack is first opened. 


Click on the background 
for options. 

Click here to dismiss 
this window 


+ 


This background of this card is covered by a large button. 
Any clicking on an area not covered by some other item will 
cause the popup shown to appear. In the next figure the user has 
dismissed the instructions and has just clicked on the back- 
ground. The popup also draws itself at a fixed location, but it 
could be at the point of the mouse click (in HyperScript this is the 
ClickLoc). 


This stack has another feature that you may choose to 
implement. One of the popups in it is controlled by clicking on 
the "filename" field in the upper right, rather than on a button. 
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This field normally contains the name of the file being edited and 
islocked text, filled in by the scripts. 


In operation a card will show the text to be edited. By 
creating new cards from this background you may have a multi 
window editor for text files. It is also useful as a note pad. 

Becareful with popups that don't disappear on mouseLeave. 
They should have at least one “Safe” option among the choices 
so that the user can make them them just disappear. 

You might want to experiment with popups which disappear 
оп mouseLeave as well as on down or up. А combination of Up 
and Leave is probably best. Note that if the popup disappears at 
mouseUp you can mouse down and then drag off the popup, and 
your initial mouseDown will be ignored. This lets your user 
avoida choice. This is not possible with a choice at mouseDown. 


SCRIPTS FOR STACK: PopupMenu 


** STACK SCRIPT МНШННШеШИРИММИИИМОНИЯЯҒЫ UE UU UN Count 
on openStack 

hide menuBer 
end openSteck 


on closeStack 
show menuBar 
end closeStack 


on startUp 

getHomelnfo 

pass startUp -- to e stertUp XCMD, if present 
end stertUp 


What you get on this month's disk 

This article is packaged with two stacks. The first is a 
practice stack to help you learn about popups. It also contains all 
of the necessary scripts, especially newPopup. The other stack 
is the simple editor described above that uses popups for its 
commands. This stack has only one card in it, but by executing 
“new Card" from the Edit menu you will build yourself a multi 
window editor for text files. 1115 also auseful textfile viewer. For 
this stack to work correctly you will need to paste the newPopup 
and selectChoice scripts, as well as the auxiliary scripts, either 
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into the Editor stack or into your Home Stack. The latter is 

preferred so that you can have popups available in all your stacks. 
The following figures are screen shots from the popup stack 

which contains all of these scripts and a few more goodies. 


Howdy 
Click above. 
A popup will 
eppear below. 


The popup is called Howdy, and its purpose is to call up 
windows that teach you about popups and how to create them. 
The first figure in this article is a card from this stack. 


Howdy 
Click above, 
А popup will 
eppeer below, 


When Howdy is clicked it brings up a popup with four 
choices. Each of these will bring up another window which has 
information about popups in it. 


Howdy 
Click above. 
A popup will 
eppeer below. 
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Ношац 
Click above. 


A popup will 
appear below. 


This stack shows ho 
do “Pop up Menus”. 

HuperCard, Bu Joe Be 
These windows wil 


| disappear if you click in 
them 


Line 1 and 2 have been clicked. The popup won't scoot until 
the browser leaves it. Thus you may make several choices on the 
same menu. Did youever wantto do that in standard Mac menus? 


Howdy 
Click above. 
A popup will 


Howdy 
Click above. 
A popup will 
appear below. 
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The user has clicked in the two windows from before. The 
popup disappeared, but it was called back and the user clicked on 
the third line. 

The user moved the browser from the popup and it went 
away. Clicking in the window showing will dispel it as well. 
Once you get used to fields as menus it is relatively simple to 
create hierarchical menus. What you need to do is have a script 
for one of your action commands call up another popup. It is easy 
to overdo this however, and your users won’t be too happy if 
every popup calls others. One of the most frustrating features of 
older computers (pre Macintosh) was having to wade through 
menu levels when you already knew what you wanted. Ah well, 
it’s nice that times have changed. Happy Computing. 

[Figure 12 Shows the Windoid type DragMenu. The method 
of scripts making objects is very powerful. As you can see from 
my additions a different type of menu can be produced. Experi- 
ment and see what you can come up with. HyperEd] 


on openStack 
hide menuBar 
end openStack 


Click on the Button 
Menu. It behaves like 
8 Windoid. 


on closeStack 
show menuBar 
end closeStack 


on startUp 
getHomelnfo 


pass startUp -- (08 
startUp XCMD, if present 
end startUp 


| This field contains 

|| the modified script 
_ | for NewPopUps. 

1 Replace the stack 

«1 script with it. 

=| Modified by 

=] Hypertd Fred Stauder 


on resume 

getHomelnfo 

pass resume -- to 8 
resume XCMD, if present 
end resume 


on getHomelnfo 
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HyperChat™ 
New HyperCard 1.2 Features 


They are listening!! 

Last month I told you to be patient with your wish lists. Well 
the good folks at Apple have answered some of your wishes. 
Hypercard 1.2 will have announced by the time you read this 
issue. The main emphasis of this issue will be the new Hypercard 
features in 1.2, also Don Koscheka joins us in bringing you 
XCMD Cookbook. 


New Features in Hypercard 1.2 
First of all Hypercard 1.2 is not the final version of Hyper- 
card, it is however an indication from Apple that they are 
committed to the evolution of the Hypercard paradigm. If you 
expected all the bells and whistles in this release you will be 
dissapointed. However Hypercard 1.2 does address lots of im- 
portant points. 
HyperCard stacks can be write-protected 
This is a very important feature that allows you to get some 
performance improvements where they are criticle, such as a 
terminal stack. You can, for example, open it locked and have a 
save button that unlocks the stack and saves the field to another 
card. 
You can recognize a write-protected stack by а padlock icon 
appearing to the right of the menu bar. When a stack is write- 
_ protected, you can’t type into any fields (even if they're not 
locked) and you can’t use certain menu items (they’re dimmed). 
You might be able to make temporary changes to acard if the 
userModify property is set to true. But as soon as you leave the 
card, the changes will disappear. 
A stack is considered write-protected under the following 
circumstances: 
• The stack is locked 
* Can't Modify Stack is checked in the stack's Protect Stack 
dialog box. 
° The cantModify property is set to TRUE. 
When the stack is locked, HyperCard automatically puts a 
check into the Can't Modify Stack option; you can't uncheck it. 
Stacks on File Servers and CD-ROM 
HyperCard 1.2 allows more than one user to browse stacks 
on file servers. Any number of users have access to a stack when 
the stack is locked (but no one can make changes to it); only a 
single user has access to a stack on a file server when the stack is 
unlocked. 
A stack is considered locked if any one of the following 
conditions are true: 
° The stack is on a CD-ROM. 
“Тһе stack ison a file server in a folder whose access privileges 
are set to Read Only. 
Тһе Locked box is checked in the stack's Get Info box in 
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the Finder. 

• The stack is on a locked 3.5-inch disk. 

Note: A locked stack is considered write-protected (see next 
card), but checking Can't Modify Stack та stack's Protect Stack 
dialog box does not lock it (even though it does write-protect the 
stack). Only locked stacks support browsing by more than one 
user. 
Auto Tabbing in Fields 
The Auto Tab option lets the Return key move the insertion 
point to the next field on the card when in the last line of a non- 
scrolling field. Auto Tab is a property of card and background 
fields. When Auto Tab is checked in the Field Info dialog box of 
a non-scrolling field, pressing Return with the insertion point in 
the last line of that field moves the insertion point to the next field 
on that card. Normal tabbing order is followed. Remember field 
order can be set by bringing the field closer or further, the order 
can be checked by the field number in the field info box. 

Setting up form type cards is now much easier where entry 


.can be done entierly via the keyboard. 


Choosing Button and Field Tools 

The shortcut for the browse tool is command-tab. Two new 
tool choices have been added. To choose the Button tool com- 
mand-tab-tab, and to choose the field tool command-tab-tab-tab. 
See —ScriptTips AutoScriptEdit-II for an alternative. 

Line Spacing Shortcuts 

Inearlier versions of HyperCard you could press Command- 
Option » and Command-Option « to increase or decrease the 
space between lines of text (the textHeight property of a field or 
of paint text). 

In version 1.2, you mustadd the Shiftkey to the formula: The 
main reason for this is to be compatible with international 
keyboards. 

First, select the field whose line spacing you want to change. 
Then press 


Command-Shift-Option > to increase the spacing 
between lines 
Command-Shift-Option « to decrease the spacing 


between lines 


Each shortcut increments or decrements the line spacing by 
1 (for example, from 16 to 17 or from 17 to 16). 


New Hypertalk Commands 


Find Command 
Find Whole and Find String are two new options for the Find 
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Command. Find Whole (ог Shift-Command-F) lets you search 
for a specific word or phrase (including spaces). It searches for 
characters at the beginnings of words. Find String lets you search 
for a specific string of characters (including spaces), but it ig- 
nores word boundaries. 

Hide Picture Command 

Hide Picture hides the picture of a specified card or back- 
ground. Hide Card Picture and Hide Background Picture hide the 


picture of the current card or background. This is very useful as 


an extra graphic layer. 

Lock and Unlock Screen Command 

Lock Screen has the same effect as setting the property 
lockScreen to true: it prevents HyperCard from updating the 
screen. Unlock Screen has the same effect as setting the property 
lockScreen to false: it allows HyperCard to update the screen. 
Unlock optionally allows a single visual effect. 

Select Command 

The Select command lets you select buttons, fields, or text in 
afield. Select Textand Select with a chunk expression let you (a) 
highlighttextina field or (b) position the insertion point ina field. 

Show Picture Command 

Show Picture shows the picture of a specified card or 
background. Show Card Picture or Show Background Picture 
shows the graphics of the current card or background. 

СІСКН and clickV Function 

The clickH returns an integer equal to the number of hori- 
zontal pixels from the left side of the card window to the place the 
mouse was last clicked 

(item 1 of the clickLoc). The clickV returns an integer equal 
to the number of vertical pixels from the top of the card window 
to the place the mouse was last clicked (item 2 of the clickLoc). 

foundChunk Function 

The foundChunk returns a chunk expression that indicates 
where the most recent Find command located its argument. Its 
result has the form: 

char «number» to «number» of «card | bkgnd» field 
«number». If nothing was found, it returns the empty string. 

foundField Function 

The foundField returns a field expression for the field in 
which the most recent Find command located its argument. Its 
result has the form: «card | bkgnd» field «number». If nothing 
was found, it retums the empty string. 

foundLine Function 

The foundL ine returns a line expression for the line of a field 
where the most recent Find command located its argument. Its 
result has the form: line «number» of «card | bkgnd» field 
«number». If nothing was found, it returns the empty string. 

foundText Function 

The foundText returns the characters enclosed in the box 
after the most recent Find command has located its argument. If 
nothing was found, it returns the empty string. 

NumberFunction 

The “number of card of <background>” is a new option for 
the function Number. It returns the number of cards in the 
specified background. 

selectedChunk Function 
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The selectedChunk returns a chunk expression that indicates 
the range of characters currently highlighted. If nothing is se- 
lected, it returns the empty string. 

selectedField Function 

The selectedField returns a field expression for the range of 
characters that is currently highlighted. If nothing is selected, it 
returns the empty string. 

selectedLine Function 

The selectedLine returns a line expression for the range of 
characters that is currently highlighted. If nothing is selected, it 
returns the empty string. 

selectedText Function 

This function returns the text that is currently highlighted. It 
yields the same result as “the selection." Note, however, that the 
selection" is a container (for example, you can put text into it); 
the selectedText is only a function. If nothing is selected, the 
selectedText returns the empty string. 

autoTab Property 

When autoTab is set to true, pressing the Return key with the 
insertion point in the last visible line of a field advances the 
insertion point to the next field on the card. Setting the autoTab 
property is the same as checking Auto Tab in the Field Info dialog 
box of a specific field. 


cantDelete Property 

The cantDelete property controls whether a user can delete 
the specified object. This property checks or unchecks the 
appropriate option on the Info dialog box of the object in 
question. 

cantModify Property 

The cantModify property lets you control whether а stack 
can be changed in any way. This property sets both the Can’t 
Modify Stack option and the Can’t Delete Stack option in the 
Protect Stack dialog box. When cantModify is true, the padlock 
symbol appears on the menu bar. 

Cursor Property 

The Cursor property has four new synonyms and four new 
options. Setting the cursor to iBeam, plus, cross, or watch is the 
same as setting the cursor to 1, 2, 3, or 4. The others are new 
cursors. (Note: “None” removes the cursor from the screen. This 
is very useful for animation you don’t get the flickering browse 
tool which was very distracting. “Busy” brings up the beach ball. 
Each time you set it, the ball rotates an eighth of a turn.) 

showPict Property 

The showPict property makes the background or the card 
picture visible (when set to true) or invisible (when set to false). 

userModify Property 

userModify is a global property that allows the user to type 
in fields and use the Paint tools in a stack that has been write- 
protected. Changes made by the user (or a script) are discarded 
upon leaving the card. This property is set to false when the user 
changes stacks or quits HyperCard. userModify has no effect on 
an unlocked stack. 

New Synonyms іп Hypertalk 

abbr, abbrev, abbreviated 

bg [new], bkgnd, background 
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bgs [new], bkgnds, backgrounds 

btn [new], button 

btns [new], buttons 

cd [new], card 

cds [new], cards 

char, character 

chars, characters 

fld [new], field 

flds [new], fields 

grey [new], gray 

loc, location 

mid, middle 

msg, message 

pict [new], picture 

poly, polygon 

prev, previous 

rect, rectangle 

reg, regular 

Script Peeking Shortcuts 

HyperCard 1.2 has several shortcuts for peeking at scripts. 
The user level must be set to Scripting (userLevel - 5) to peek at 
scripts. 

While using the Browse tool: 

Command-Option: Peek at all visible buttons; click one to 
see its script. 

Shift-Command-Option: Peek at all visible buttons and 
fields; click one to see its script. 

While using the Field tool: 

Command-Option: Peek at all visible and invisible fields; 
click a visible field to see its script. 

While using the Button tool: 

Command-Option: Peek at all visible and invisible buttons; 
click a visible button to see its script. 

While using any tool: 

Command-Option-C: Peek at the script of the current card 

Command-Option-B: Peek at the script of the current back- 
ground 

Command-Option-S: Peek at the script of the current stack. 

To put any script away quickly once you are in the script 
editor, press Command-Option again and either (a) click once or 
(b) press any key. 

I hope we can all remember these key combinations; does it 
remind you of IBM function key nightmares? How about having 
them in hieracial menus for the times we forget and the not so 
power users and developers that would like to use them. If I 
remember my human interface guidelines correctly command 
keys should be a supplement to menus. 

The New "Me" and "Target" 

put the target — still puts the name of the object that last 
received a message 

put target into myVar — puts contents of a field into a 
variable 

put "Fred" into target — puts "Fred" into the field 

Note: “рш value of the target" is equivalent to "put target." 

The above changes affect only operations on fields, not 
operations on buttons, cards, backgrounds, or stacks. 
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retuminFieldSystem Message 
If the returnInField message is not intercepted by a handler, 


HyperCard checks to see if the autoTab property of the current 
field is true. If itis and the insertion point is on the last line of the 
field, HyperCard sends the tabKey message to the current field. 
Then if the tabKey message is not intercepted by a handler, the 
cursor moves to the next field on the card. 

enterinField System Message 

If the enterInField message is not intercepted by a handler 
and the contents of the current field have changed, HyperCard 
sends the closeField message to the current field. 

Rects 

You can now access parts of the rectangle of a specified 
object and test whether a point is contained within a rectangular 
region. 

In the following descriptions, the symbol «rect» means апу 
expression that yields a rect. A rect consists of four integers, 
separated by commas, that specify the top-left corner and bot- 
tom-rightcorner of arectangle as offset in pixels from the top-left 
corner of the card window. The order of the integers in a rect is 
Left, Top, Right, Bottom. 

Forexample, the following are examples of expressions that 
yield a rect: 

rect of card field 1 
rect of first btn 
rect of tool window 
rect of pattern window 
rect of msg box 
rect of card window 
* There is anew function, the screenRect, that returns the rect 
of the entire screen in which the HyperCard window resides. 
Since it is a function, you cannot use it with Set. 


get the screenRect 


* Using «rect, the following new properties сап be defined: 


left of «rect» 
is equal to item 1 of «rece 


top of <rect> 
is equal to item 2 of <rect> 


right of «rec 
is equal to item 3 of «rect 


bottom of «recb 
is equal to item 4 of <rect> 


topLeft of «rect» 
is equal to item 1, item 2 of «rect» (or the top-left corner 
point) 


bottomRight of «rect» or botRight of «rece 
is equal to item 3, item 4 of rect (or the bottom-right corner 
point) 
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width of «rect 
is equal to (item 3 of «rect» - item 1 of <rect>) 


height of «rect» 
is equal to (item 4 of <rect> - item 2 of <rect>) 

* Youcan use Set with left, top, right, bottom, topLeft, and 
bottomRight to move the specified object. For example, “set left 
of background button 3 to 25." Note: You cannot Set the 
screenRect. It is a pity you could do some interesting things with 
it. 

° Youcanuse Set with width and height toresize buttons and 
fields.For example, “set width of background button 3 to 25." 
Note: You cannot resize the message box, the tool window, the 
pattern window, the card window, or the screenRect. When 
changing the width or height, HyperCard maintains the loca- 

tion or loc (center coordinate) of the object, expanding or 
shrinking it on both sides evenly. If either property is 
changed by an odd amount, then HyperCard adds the odd 
pixel either on the right (with width) or on the bottom (with 
height). 


* HyperCard Version 1.2 has a new operator, Within, that 
allows you to ask if a point is contained in the region defined 
by arect. Itreturnsa boolean value (true or false) and is used 
as follows: 

«point» is within «rect? 
«point» is not within «rece 
For example: 
“12,34” is within “45,45,100,100” 
the clickLoc is within the rect of button 3 
the mouseLoc is not within the rect of me 


Consistent with the Macintosh's rules about rects, the top 
left point of a rect is within the rect; the bottom right point of a 
rect is not within the rect. 

As youcan see there are many new features in Hypercard 1.2 
take the time to explore them fully, there is a lot more power in 
these changes than is obvious at first. Next month I will show you 
some example stacks that take advantage of the new features. 
Some of this information was obtained from the vesion 1.2 
release notes from Apple Computer. 

ScriptTips 

Theresponse to AutoScriptEdit was so intense that I decided 
I had to expand it and make an even more powerful version. 
AutoScriptEdit-II will get the script of an unlocked field as well 
as locked fields. I thought what are some of the frustrating things 
that can be improved upon. The answer I came up with was 
locking and unlocking fields. Now if you hold down the enter key 
and mouse button the field will toggle between locked and 
unlocked. I am using mouseStillDown because it is used much 
less than mouseDown. Another feature that I have added, to 
demonstrate how one key can serve two purposes, is showing the 
tool window at the mouseLoc using option-click. This is much 
more useful than the standard option-tab because it pops up 
where you want it. Ihave used AutoScriptEdit to demonstrate the 
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power of gestural commands, i.e. holding the mouse down and 
moving off the top of the card to get the stack script. 


— AutoScriptEdit-II by Fred Stauder May 1988 — 


- Put this Script into your Home Stack 

- To use keep mouse btn down over Button or Field andmove - 
mouse up 

- To edit Bkgnd Script keep mouse btn down move mouseto -left 
of cerd 

— Card Script - move right 

- Stack Script - move up 

- Now works with unlocked f ields 

- To lock and unlock fields option click in them 

- To show tools at cursor hold option click on non- 
ereas 


field 


on mouseStillDown 
if the optionkeu 1$ down then 
if the target contains “field?” then set locktext of target 
to false 
else show tool window at the mouseloc 
end if 
put char 6 of the target into C6 
if C6 is quote then AutoScriptEdit 
if Сб is “i” then AutoScriptEdit 
if Сб is quote then exit mousestilldown 
if Сб is 41” then exit mousestilldown 
if the mouseV «item 2 of rect of target then edit script of 
terget 
pass mouseStil 1Down 
end mouseStillDown 


on AutoScriptEdit 
if the mouseH < 2 then edit script of this bkgnd 
if the mouseH › 510 then edit script of this card 
if the mouseV < 2 then edit script of this stack 
end AutoScriptEdit 


on openf ield 
if the mouseV <item 2 of rect of target then edit script of 
target 
if the optionkey is down then set locktext of target to true 
pass openfield 
end openf ield 


Non-Comercial use only - All Rights Reserved 
Fred Stauder, Hypercard Editor, CHyperChat) MacTutor 


SpeedTips 

To get more performence out of your stacks especially with 
graphics you can “Preload” cards by setting lockscreen and going 
to those cards. This is particularly important if you are doing 
animations. 

Another speed tip is to use the link button to get the id of a 
card rather than a name, it is a good idea to put the name in 
comments so that people reading your scripts have a better idea 
what is going on. 

The last SpeedTip for this month is put commonly used 
information in globals rather than having to go to a card to get the 
info from a field. Send your Articles, ScriptTips, etc. to: 

Fred Stauder 

Ecofin Reseach and Consulting 


Lavaterstrasse 45 gr 
Zurich 8002 e 
Switzerland 


Applelink D0280 or 
To the MacTutor Office, PO Box 400, Placentia, CA 92670 
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HyperChat!M 
. XCMD Cookbook 


[Donald Koscheka is a Software Engineer employed by 
Apple Computer Inc. He has written some very important devel- 
opment XCMDs which you will hear about soon. -HyperEd] 


Introduction to XCMD's 


If you've used Hypercard and its programming language 
HyperTalk for any length of time, you've no doubt discovered 
some of the things that you can't do with Hypercard. Perhaps 
you're writing a forms generator in HyperTalk and you want to 
be able to print customized reports. The designers of Hypercard 
knew that their product would have to be a lot of things to a lot 
of people and it would be nearly impossible to provide every 
possible feature in the language. They did, however, provide us 
with the capability of customizing HyperCard and HyperTalk 
directly. To paraphrase Abraham Lincoln, “Ү ou can fool some 
of the people all of the time, or all of the people some of the time, 
but to fool all of the people all of the time, write an XCMD". 

Ав a programming language, HyperTalk is highly exten- 
sible; you can add your own commands and functions to the 
language very easily. These extensions are known as eXternal 
CoMmanDs ( XCMDs) and eXternal FunCtioNs (XFCNs). The 
capital letters, ie. case, are significant as ГИ discuss later. 
XCMDs and XFCNs are identical at the coding level, so I'll refer 
to both as XCMDs. The determination of whether a command 
will be an XCMD or an XFCN is made at link-time. 

Creating an XCMD is a straightforward process. First, you 
write the XCMD using the language of your choice (ГІ show 
examples in both *C" and Pascal). Next, you compile and link the 
XCMD as a resource and then you add it to the resource fork of 
the stack that you want to call it from, the home stack or even 
Hypercard itself. 

Where you put the XCMD is significant. When Hypercard 
encounters a command that it does not recognize, it first checks 
the current object (button or field) to see if it contains any 
handlers for that command. If no handler is found, the search 
continues in the following order: card, background, stack, home 
Stack, HyperCard. If after looking in all the places that it could 
expect to find a handler no handler turns up, Hypercard then 
searches its own resource fork for any external commands that 
can handle the command. It identifies the appropriate command 
by name. Note what this hiearchy implies. If you want your 
XCMD to be globally visible to all stacks, put the XCMD in 
HyperCard's resource fork or Home Card. There is a tradeoff, 
though. If you want the stack that uses the XCMD to be 
“portable”, you'll need to put the XCMD in that stack. There is 
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noconflict of interest here, you can put the XCMD in both places. 
[Use Rescopy , via scripts, to allow the user the option of 
installing it into the Home Stack. -HyperEd] НурегсагА stops 
searching as soon as it finds a copy of the command. If it finds 
а copy in your stack, it'll stop the search there. If you call the 
XCMD from another stack that does not contain the XCMD, then 
it'll go all the way back to the Home Stack or Hypercard to search 
for the command. 

Now that you have an idea of where to place the XCMD, let's 
take a look at how they are created. All XCMDs and XFCNs 
interface to Hypercard in a standard and straightforward way. 
When an XCMD is invoked, Hypercard will pass it a parameter 
block that contains, among other things, the number of parame- 
ters and handles to the parameters. For argument's sake, let's see 
how the following XCMD would be called: 


Pizza “Cheese”, “Pepperoni”, “Anchovies” 


When this XCMD is called, Hypercard will pass a record, 
referred to as the Parameter Block, to the XCMD. The first 
argument in the parameter block will be the number of parame- 
ters passed; in this case three, one for each item in the argument 
list. Each parameter is passed as a handle to a zero-terminated 
text string. Parameter 1 will be a handle to the string “Спеезе\0”, 
where the the 40” means the character whose ASCII value is 0. 
“C” programmers will recognize this format as a standard string 
definition in “С”, Pascal programmers often refer to this format 
as a C-String. The actual structure of a parameter block (in 
Pascal) is: 


TYPE 
XCmdPtr = *XCmdBlock; 
XCmdBlock = 
RECORD 
peremCount : INTEGER; 
params : АККАУ[1.. 16] OF Handle; 
returnValue : Handle; 
passF lag : BOOLEAN; 
entryPoint ProcPtr; ( to call back to HyperCard ) 
request INTEGER; 
result INTEGER; 
inArgs ARRAY[1..8] OF LongInt; 
outArgs АЮКАҮ(1..41 OF LongInt; 
END; 


Let's examine this record in more detail. First, we define a 
pointer to the record, called an XCmdPtr. Hypercard passes а 
pointer to the record so you'll need to be comfortable with 
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pointers to work with XCMDs. 

The first field in the record, paramCount , is a count of the 
number of parameters that have been passed to the XCMD. This 
is a number between 1 and 16, which is the maximum size of the 
parameter array, params, in field 2. Params is an array of handles 
which implies that the fundamental element in the array is a 
signed byte. 

Field 3 in the record, returnValue, is a handle to the data that 
you want to return to Hypercard on completion of the XCMD. 
You create the handle and pass it back to hypercard with the 
assignment: 

paramPtr*.returnValue :- Handle. You Created; 

Herein lies the most important difference between XCMDs 
and XFCNs. RetumnValue os places in the global container, 
result, when returning from an XCMD and by value when 
returning from an XFCN. The following illustrates the mechan- 
ics: 


KD. Ае еее “pepperoni”, “anchovies” 
U e resu 


ХРОМ: Put Pizza (“сһееве”, “pepperoni”, "anchovies^) 


XCMDSs, like any other command in hypercard, take their 
parameters оп the same line as the command itself. XFCNS, like 
any other function in Hypercard, take their parameters in paren- 
theses and return a value. This is the most important difference 
between XCMDs and XFCNs. You make the decision at link- 
time as to whether a code resource will be an XCMD or an XFCN. 
Please note, the code is identical for both XCMDs and XFCNs. 
Hypercard re-vectors ReturnValue for you depending on 
whether you invoked an XCMD or an XFCN. 

The next field, passFlag, should be setto TRUE if you want 
Hypercard to pass the command on in the hierarchy after invok- 
ing the XCMD. Most of the time, you won't concern yourself 
with this field. 

The next five fields in the parameter block are used for 
making callbacks to Hypercard [the subject of the next article - 
DK]. Callbacks allow you to invoke some hypercard commands 
from within an XCMD, quite a useful feature. An example of a 
callback is GetFieldByNum which will return a handle to the data 
ina fieldon thecurrentcard. This is analogous to “Се! card field 
1” in HyperTalk. 

EntryPoint is set by Hypercard on entry to the XCMD and 
is used as a jumping off point for invoking callbacks. In effect, 
Hypercard will execute a jump instruction to EntryPoint for all 
callbacks. But before executing the jump instruction, Hypercard 
will place an integer value into the Request field. This integer 
tells Hypercard which callback to execute. The code at en- 
tryPoint will vector to the appropriate routine based on the value 
in Request. 

Uponreturning from a callback, Hypercard will have set the 
value of the Result field to some integer value to tell you how 
things went in the callback. A value of O indicates that no error 
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occurred in the callback, 1 indicates that the callback failed for 
some reason or other and 2 indicates that the callback is not 
implemented. 

The next to last field in the record, inArgs, is an array of up 
to eight input arguments to the callback. Although the argu- 
ments are passed as longInts (long in “С”), they may contain 
anything. Generally speaking, the Hypercard callback glue will 
handle type-casting for you. 

Finally, callbacks can return up to 4 parameters in OutArgs. 
These parameters will be set by the callback and available to you 
from thecalling XCMD. Callbacks are glued to the XCMD using 
standard Pascal interfaces so they're pretty easy to get along with. 

Callbacks are a useful and powerful tool available to the 
XCMD programmer. Currently, Hypercard includes about thirty 
callbacks and I'll discuss each one in more detail next month. 

The foregoing discussion implies that you'll mostly concern 
yourself with the first four fields in the record and let Hypercard 
manage the callback parameters. In practice, you'll mostly be 
concerned with paramCount, params and returnValue. 

For the sake of ош “С” readership, here's the definition of 
the parameter block as a “С” structure: 


typedef struct XCmdBlock ( 


short peremCount; 
Handle params[ 16]; 
Handle returnValue; 
Boolean passF lag; 
char *entryPoint; 

shor t request; 
short result; 

long inArgs [8]; 
long outArgs [4]; 


} XCmdBlock, *XCmdBlockPtr; 


АП Input and Output to an XCMD is passed through the 
parameter block. Armed with this information, here is a simple 
XCMD that does absolutely nothing (note: Iuse MPW Pascal and 
“С” in my examples). 


(жж) 


(ж File: SimpleXCMD.p к) 
x x) 
o Shell for XCMDs end XFCNs in MPW Pascal <) 
Ж es Jf 

(ж In:  paremPtr = pointer to the XCMD x) 
(* Parameter Block x) 
(* x) 
(* -------------4) 

(* € 1988, Donald Koscheka х) 
(* x 


(Y Y13333 ЖЖ ЖЖ KERR ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ХХХ x) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
BUILD SEQUENCE 

pascal SimpleXCMD.p 

link -m ENTRYPOINT -rt XCMD=6555 à 
-sn Main-SimpleXCMD д 
SimpleXCMD.p.o à 
* (Libraries)"Interface.o д 
* (PLibraries)"Paslib.o à 
-о *(xcmds) "your stack here 


585 


ЖЖЖЖУЖ ЖЕ ЖЖ Х ) 

($S SimpleXCMD ) 

UNIT Donald. Ковсһека; 

INTERFACE 
MemTypes, QuickDrew, OSIntf, ToolIntf, 
PackIntf, HyperXCmd; 

PROCEDURE EntryPointC paramPtr: XCmdPtr); 

IMPLEMENTATION 

($8-) 

YPE 

Str31 = String(31); 

PROCEDURE SimpleXCMDCparamPtr: XCmdPtr); FORWARD; 


(— ——EntryPoint 

PROCEDURE EntryPoint(paramPtr: XCmdPtr); 
BEGIN 

Simp leXCMDCparamP tr ); 

END; 


( бітпрлехсМ0----) 
PROCEDURE SimpleXCMDCparamPtr: XCmdPtr); 
VAR 

i : INTEGER; 


($I XCmdGlue.inc ) 


BEGIN 
WITH paramPtr~ DO 
BEGIN 
returnValue := NIL; 
END; 
END; 
END. 


The Build sequence for this file is included in the header for 
the sake of convenience. After the compilation, we need to link 
the code into a resource and add it to some stack. First, let’s take 
acloser look at the link options. The “-m ENTR YPOINT” option 
tells the linker that the first line of executable code in the resource 
is at the label ENTRYPOINT. Next, the “-rt XCMD=6555” 
option tells the linker that this file whould be written as a resource 
of type ““XCMD” and should be assigned a resource ID of 6555. 
Because we are writing the resource directly out to the stack 
named "your. stack here", any XCMD with ID 6555 will be 
overwritten by this link. To link the code as an XFCN, use “-rt 
ХЕСМ=6555”. That's about the only difference between 
XCMDs and XFCNs! 

You must remember to note that resource types are case 
sensitive. Telling the linker to set the resource type to "xcmd" 
will work fine, only Hypercard won't recognize the resource as 
an XCMD. As far as numbering XCMDs goes, I don't know of 
any rational system that's been implemented yet. Follow the 
number guidelines provided in Inside Macintosh, Chapter five. 

The option *-sn MainzSimpleXCMD" tells the linker to 
change the segment name of the main segment from “Маш” to 
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“SimpleXCMD”. “SimpleXCMD.p.o” is the name of the input 
file, the library includes follow. The last line “-o 
your stack here" instructs the linker to add this XCMD to the 
resource fork of the stack whose name is *your stack here". 
Remember to include pathnames in your build. 

The build sequence for XCMDs is pretty much a boiler- 
plate. You'll change type from XCMD to XFCN, the ID to 
whatever you want, and the input and output lines. About the 
most important addition you might make to the build is to add 
libraries as needed. 

The XCMD itself follows the standard layout for a Pascal 
Unit. The unit name is inconsequential to us. A lot of program- 
mers use “UNIT dummyUnit" to remind themselves of that . I 
use my name instead. 

The interface portion is straightforward. Tell the compiler 
what files you want to include and declare the interface to your 
routine. Note that we use *EntryPoint" and not "SimpleXCMD" 
as the main entrypoint for this routine. I'll leave itas an exercise 
to the student to figure what that's all about. 

Note the use of the {$R-} directive in the implementation 
section. This turns off range checking and results in more 
efficient code. Although we don't use the Str31 type declared in 
the TYPE statement, it is needed by the callbacks so we MUST 
include it here. 

Procedure SimpleXCMD contains the actual code for the 
XCMD. Note that it takes exactly one parameter, a pointer to an 
XCmdBlock. Although the VAR statement is not used in the 
body of the code, I included it here so that those of you that are 
less fluid in Pascal can clearly see that the ($I XCmdGlue.inc) 
directive follows the CONST, TYPE and VAR declarations 
within SimpleXCMD. XCMDGlue contains the glue routines 
for the callbacks. They are simple compiled with the rest of the 
code. Because of the scoping of procedures feature of Pascal, the 
glue routines will be able to access paramPtr directly, you won;t 
need to pass it to each routine in turn. 

Finally, the body of the program. Here we simply set the 
returnValue to NIL and exit. If you already have code that you 
want to implement in an XCMD or XFCN, replace the body of 
SimpleXCMD with the body of your routine and off you go! 


PROCEDURE SimpleXCMDCparamPtr: XCmdPtr); 
VAR 
i : INTEGER; 


($I XCmdGlue.inc ) 
BEGIN 
WITH peramPtr* DO 
BEGIN 
returnValue := NIL; 


; 


END; 


XCMDs in “С” are different enough in implementation to 
bear some discussion. Here is SimpleXCMD in “С”: 


[ E XXXOCEE ЖЖ ЖЕ ЖЖ ЖЖ ЖЖ ХХХ ХХХ ХХХ AAA AA EAE \ 


* file: SimpleXCMD.c * 
x x 


х XCMD shell in MPW "C^ ы 
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С -q2 SimpleXCMD.c 
link -sn Main=SimpleXCMD à 
-sn STDIO-SimpleXCMD à x 
-sn INTENVsSimpleXCMD -rt ХСМ0-3019 * 
SimpleXCMD.c.o -o your_stack_here * 
x 


* 2 м 


If you use parts of the "С” * 
Librery, use this x 
link instead: 


link -sn Main-SimpleXCMD -sn 9 
STDIO=SimpleXCMD д 

-sn INTENV=SimpleXCMD -rt ХСМ0=30 19 
-m SIMPLEXCMD SimpleXCMD.c.o д 
* (CLibraries)"CRuntime.o д 
* (CLibraries)^CInterface.o д 
-0 your.stack. here 


є 3€ 3 93€ X ии м жн 


— P — MORET. ‹ 
By: Donald Koscheka 
Date: 21-Sept-87 

€ Copyright 1987, Donald Koscheka 
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X ———————— * 
\ХЖЖЖЖЖЖЖЖ ЖЖ ЕЖА ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ / 


"include «Types.h? 
"include «0SUtils.h» 
8include «Memory.h? 
8include «Files.h? 
include «Resources.h? 
include “HyperXCmd.h” 


pascal void SimpleXCMD(C paramPtr ) 


XCmdBlockPtr paramPtr; 
ЫЫ 22 53222 32555 222222555. 


ж SimpleXCMDC) 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ / 


( 


paramPtr->returnValue = nil; 


®include <XCmdGlue. inc.c) 


SimpleXCMD0O is defined as a Pascal Void to tell the “С” 
compiler to push the parameters “Pascal Style”. This means that 
parameters are pushed from left to right rather than from right to 
left. Also, we need to inform “С” that this function does not 
return a value, so we qualify the type with “void”. Otherwise, 
“С” will leave room on the stack for an integer-wide return value. 

An important difference between the two languages is that 
“С” does not allow scoping of procedures. The callback glue 
routines are not local to SimpleXCMD as is the case in Pascal. 
For this reason, when calling glue routines from “С”, the first 
parameter passed must be a pointer to the XCmdBlock. 

When you start programming XCMDs, you may encounter 
a seemingly nebulous link error, “Мо Data Initialization". Тһе 
linker is telling you that there is no global memory to initialize for 
the XCMD. XCMDs are code resources, they are designed to be 
called "subroutine" fashion from Hypercard and as such do not 
have access to their own globals. Put another way, Hypercard 


owns the global pool from which XCMDs may draw. This means 
thatthe only kind of datathatcan be declared in an XCMD islocal 
data, also known as automatics. Automatics get created on the 
stack and exist only for the life of the XCMD. When the XCMD 
returns to Hypercard, the local memory pool goes away. 

You are most likely to encounter a problem with this when 
using strings in *C". Consider the following code fragment: 


char *myStr; 


mystr = “Colleen’; 


In this code, I declare a string pointer called myStr. I then 
point this string pointer at the properly formed string ‘Colleen’. 
This code will compile correctly but the linker will not be able to 
work with it. When “C” compiles strings in-line, it actually puts 
the string into the global pool and points myStr at the string in 
global memory. Since the XCMD is assembled without global 
memory, the linker won’tknow what to do with this code. Pascal 
does not suffer this fate because it does not put the string into 
global memory. The following code will compile and link just 
fine in Pascal: 


myStr : StrPtr; 


myStr := ‘Margaret’; 

The reason this works in Pascal and not in “С” is that Pascal 
tacks the string “Margaret” onto the end of the code resource, 
rather than put the string into global memory. 

The upshot of this diatribe is don’t declare global variables 
from XCMDs. If you need to use strings іп “С”, you'll need to 
hard-code the assignments: 


sitit 
myStr[2] 
myStr [3] 
myStr[4] 
mystr [5] 
муз {г [6] 


nyStr(7]» 40” 


“ut H M HN 
b 
— 
` 


If your going to be using a lot of strings,I would suggest that 
you either put them in resources (yuck!) or use Pascal instead. 

This article presented the basics of XCMD programming 
and describes how to interface your code to Hypercard. Next 
month ГІ introduce the callbacks and give some examples how 
they can make XCMD programming easier and more fun. If 
you're already an experienced Macintosh programmer, the 
above is information enough to get you started on XCMDs. If 
you're just getting started, this article should be just enough to 
help you get started, without being too much, to get you lost. 


@ The Definitive МасТшог, Vol. 4 


587 


HyperChat™ 


HyperTools For HyperProgrammers 


on HyperChat 

— HyperEditorlal 

This month we have a section on new tools that will aid 
development of your Hypercard Stacks. Also Don Koscheka will 
bring you another XCMD Corner where he shows how to do 
callbacks. 

—ScriptTips 

Last month I brought you AutoscriptEdit-II which allowed 
you to lock and unlock fields, to put up the tool windows, and to 
edit the script of an unlocked field. Some of you may have come 
across a bug which was a bit of a problem. When you “Tabbed” 
from field to field if the mouse was higher than the field the edit 
script would be invoked. What I have done in version III is to 
enable the edit script only with the option key. It seems that it is 
a current limitation of Hypertalk that I can't get around it in a 
neater way. I will be trying for a fix in Hypertalk to correct this. 
Another neat thing that I have added to version III is a feature that 
will allow you to *hide" Hypercard when you are in MultiFinder. 
First click in the top left corner of the card, this moves the card 
window up and left so that only a small section is still showing. 

To return the window to the original position click in the 
small section of hypercard remaining. This should work in most 
stacks if you have AutoscriptEdit-III in your home stack. 

For the occasions where it does not work, if there is a button 
over it etc., simply go home and then click in the corner. Next 
month I will bring you a really exciting extension to Au- 
toScriptEdit and possibly in a self-installing button which will 
give you a toggle in your home stack such as "Power Keys". 


AutoScriptEdit-III by Fred Stauder June 1988 
- Put this Script into your Home Stack 
- To use keep mouse btn down over Button or Field and move mouse 


up 

- To edit Bkgnd Script keep mouse btn down move mouse to -left of 
card 

– Card Script - move right 

- Stack Script - move up 

- Now works with unlocked fields 

- To lock and unlock fields option click in them 

- To show/hide tools/patterns at cursor 

- hold option click on non-field areas 

- bug fixed tab fields, needs option-move up on unlocked fields 
-click in top left corner to hide card window, botom right to show 


on mouseStillDown 
global CWLoc 
if the optionkey is down 
then 
if the terget contains *field^ then set locktext of terget to 
false 
else 
if the optionkeu is down then 
set the visible of pattern window to not the visible of 
pattern window 
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HuperCard 


set the loc of pattern window to the mouseloc 
set the visible of tool window to not the visible of tool 
window 
set the loc of tool window to the mouseloc 
exit mouseStillDown 
end if 
end if 
end if 
if the mouseloc is within “0,0, 10, 10^ 
then 
put the loc of card window into CWLoc 
set loc of сага window to -504,-315 
exit mousestilldown 
end if 
if the mouseloc is within ”500,333,512,346” 
then 
set loc of cerd window to CWLoc 
exit mouseStillDown 
end if 
put char 6 of the terget into C6 
if C6 is quote then AutoScriptEdit 
if C6 is “i? then AutoScriptEdit 
if Сб is quote then exit mouseStillDown 
if Сб is "i^ then exit mouseStillDown 
if the mouseV <item 2 of rect of target then edit script of target 
pass mouseStillDown 
end mouseStillDown 


on AutoScriptEdit 


if the mouseH < 2 then edit script of this bkgnd 

if the mouseH » 510 then edit script of this сага 

if the mouseV < 2 then edit script of this stack 
end AutoScriptEdit 


on openf ield 
if the optionkey is down 
then 
if the mouseV <item 2 of rect of target 
then 
edit script of target 
set locktext of target to false 
exit openf ield 
end if 
set locktext of target to true 
end if 
pass openfield 
end openf ield 


Non-Comercial use only - A11 Rights Reserved 
Fred Stauder, Hypercard Editor, CHyperChat) MacTutor 


-HyperTest 


HyperTools for the HyperHacker 

Softworks Inc. has released two tools to help develop stacks. 
Hypertools #1 is mainly aimed at stack developers and Hyper- 
tools #2 helps with formatting and customizing stacks. 

Each stack contains 16 tools, four tools are common to both; 
scan tools, font tools, stack stats, and free space. 

The presentation of Hypertools is very good and shows how 
a product can be made from individual smaller subunits. 
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Radio Btn Group Checkbox Group | Button Tools 


6 = 


Cursor Tools Alignment Tools Edit Script Tool 
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Font Tools Array tools Stack Watch Stack Stats 


inst d ] 


aH e m 


info Tools Get Line Number 


Гас 


Huntington, СТ 


figure 1. HyperTools#1 

The interface is very good with a consistent style throughout. 

HyperTools incorporates a feature they called “scanning”. 
When you click on a scan icon you can move between various 
cards in your stack by simply moving the mouse left to scan 
through previous cards; or to the right to scan through following 
cards. To stop at a card you click the mouse button. 

You can perform scanning at two speeds: Normal Speed, 
when no keys on the keyboard are depressed; or Faster when the 
Shift Key on the keyboard is depressed. You can also automati- 
cally sequence through all of the cards by holding down the 
Option Key, the Scan tool will then continue sequencing through 
each card (left or right) until you release the option key. 

Whenever you are scanning backwards (moving the mouse 
left), the cursor will change to an outlined arrow pointing left, a 
right arrow when going forward (moving the mouse right) and an 
arrow going in both directions when the mouse is not moved. 


A well set out tool is the neat icon editor that integrates the 
best parts of Hypertalk and XCMD's. 

The Icon Editor presents a list of all of the accessible icons 
in the current stack, Hypercard and the System file. By clicking 
on an entry in the field list, you can see the actual icon. By 
selecting the Edit Button, you can modify an existing icon. You 


<n [ СОП Editore 


Edit Icons 


Current Modified 
Icon Icon 


Available Icons 
1006, Hac 
1007, ImageWriter 
1008, LaserWriter 
1019, ResEdit 
26884, Art Ideas 
16614, Card Ideas 
27056, Button Ideas 
15420, Sml Prev Arrow 
16560, SmI Next Arrow 
6720, Sml Return Arrow 
16692, SmI Up Arrow 
3584, Sm! Down Arrow 


а 


= L 


| (Save Modified Icon. (Save Modified Icon) Icon 
k: 
соп ID Seve medica teon) 
ИШ 
icon Nance _______ 


figure 2. Icon Editor Tool 
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can also Clone (make a new copy of) an existing icon, or create 
a brand new icon. When editing an icon, all of Hypercard’s 
drawing features are available. You can even paste in a picture 
from Hypercard or the scrapbook to create the icon. This will 
save time going to ResEdit and back. 


Radio Button and Checkbox Group tools: 

The Radio Button Group Tool lets you create the scripts for 
radio buttons and checkboxes on a card or background. The 
scripts for the radio buttons allow you to click on one button of 
the group and turn off all other buttons of the group automati- 
cally. The checkbox tool is similar. 


The Button Tool gives you a pallet of common Buttons with 
their scripts. Not very exciting but still useful. What would be 
good is if you could add your own buttons to this tool. 


The Cursor Tool shows all the available cursors, a cursor 
editor would be interesting. 


The Alignment Tool allows you to select multiple cards or 


Radio Buttons on Bkgnd 
o 


18, Оп Bkkg 
20, Оп Bkkg 


figure 3. Radio Button Tool 


background fields and buttons and perform various repositioning 
actions on them asa group. Youcan also align and move elements 
to a grid which you can define. 

This is a well thought out tool and is very useful. 

The Edit Script Tool is a button that you push before you 
click on the button to edit the script. 

The Font Tool allows you to select multiple fields and/or 
Buttons on a card or background and change the font, the size, 
style, and the text alignment of selected items. You can quickly 
change the characteristics of all selected items. 

The Array Tool allows you to add automatically rows and 
columns of fields or buttons at one time. This is a great little tool 
that saves time when you have to do repetitive creations. 

The Stack Watch Tool adds commands to your stack script. 
This code is executed each time you run the stack. It will notify 
you whenever the free size of the stack exceeds 100K. Then it 
asks you if you want to compact. 


The Stack Stats Tool quickly summarizes information about 
the current stack including the number of backgrounds, cards, 
and buttons and fields on cards and backgrounds. An example is 
shown on the next page 
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Alignment Tools 
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figure 5. Font Тоо! 


The ХСМ Tool quickly summarizes all of the accessible 
XCMD and XFNC that are installed in the current stack and 
Hypercard. 


The Info Tools allows you to create various cross reference 
listings of the current stack. The listings created by these tools are 
displayed on the screen. You can also choose to print them or 
export them to a file on disk for use with a word processing 
program. You сап create a list of all message handlers, references 
to a global variable or search for any string. For these functions, 
you can choose to search all scripts or choose from any combi- 
nation of: the stack script, background scripts, background but- 
ton and background field scripts, card scripts, card button or card 
field scripts. 

If you search scripts for a string, a list detailing the number 
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Create firrays 


Q Rectangle Buttons 
(8 CheckBon 

C) Radio Button 

Q Rectangle Fields 
C Opaque Fields 

С) Transparent Fields 
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Size (ш,һ) 


[create | Done ` 


figure 6. Array Tool 


This Stack contains: 4 beckgrounds; 6 Bkgnd 
fields; 21 Bkgnd Btns; 6 Cards; 66 Card Fields; 
and 161 Card Btns. 


figure 7. Stack Stats Tool 


of occurrences will be displayed on the screen. 

You can also create a list of all card buttons, background 
buttons, card fields or background fields. For these functions you 
can choose to do the entire stack or a specific card. 

The listings created by these tools are displayed on the 
screen. You can also choose to print them by selecting the Print 
button on the screen. You can also ехрог listing you created to 
a file on disk for use with a word processing program. 

The Get Line Number Tool, lets you automatically create 
code,fora scrolling field on a card or background which returns 
the line number when the user clicks in it. 

The Free Space Tool tells you how many bytes can be 
compressed from the current stack and allows you to compact the 
stack automatically. 

Tools in HyperTools #2 

The Choice List tool allows you to assign a list of selectable 
entry choices to a card or background field. Each stack may have 
up to 42 different choice categories. Clicking on the "Link a 
Choice List" icon will display the current list of all available 
categories. You can modify, delete or create categories from the 
window which is displayed. To add a choice list to a card or 
background field, click on a category from the window. 

The Field Validation Tool lets you create a script for a card 
or background field which verifies that the information entered 
is a valid Hypercard Number or Date. You can also define 
whether any field on the card or background is required during 
entry. 
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List of message handlers found in stack "40SC:HuperToo!s 91". 


stack "HyperToo! s 91" 
on rotate_Cursor 
function wi thinRect therect 
function DupChars thechars,count 
function Tool Exists TheBtrName 
on Hide Others ThisTool 
function Loop. tems BC, iType, 21, 22, DestField 
function Get ол. | tem Types, z 1,22, DestField,Too Мате ‚ВС 
сп mousedown 
Function GetLloc-Dalta a 
Function ScanTo dowhat 
function StripMsg douhot, newSer, zscr, thensg 
bkgnd "Тор Bkgnd" id= 2704 @ | 
bkgnd button "Cursor Tools" id= 18 Өз | 
сп mouseUp 
bkgnd button "Checkbox Group" ids 20 Әз 2 
on Del FB 


[ List Hendlers Щ List Card Btns B List Сага Fields Щ Print Ë Export | 


figure 8. Info Tool 
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figure 9. HyperTools #2 


The Display Format Tool allows you to add a script to acard 
or background field which will reformat the content of a card 
field whenever it is modified. You can select from the following 
display formats: number, date or text. This tool first allows you 
to scan to the card where the tool is to be installed. 

The Visual Effects Tool displays a screen with buttons 
representing the various special effects that can be added to cards 
of your stack. 

The Group Tools allow you to select multiple cards or 
background elements and perform various repositioning, copy- 
ing and deletion activities on them as a group. This is very similar 
to the array tool in HyperTools 1. 

The Global # Format Tool allows you to specify 
Hypercard's default precision for numbers and mathematical 
activities. When you click on this icon, a dialog showing the 
default numeric precision value is displayed. 
| The Sound Tools allow you to create and modify musical 
tunes. Sounds available in the current Stack and Hypercard are 
displayed in a scrollable list. Clicking on an entry from the list 
will change the current tune settings to use the selected Sound. 
Youcancreate tunes using the piano keyboard which is displayed 
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figure 10. Choice List Tool 
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figure 11. Field Validation Tool 
on the top of the screen and play them with any Sound and at any 


tempo you specify. You can also directly modify a tune using the 
editable field provided. 


The ViewFont Tool allows you to view the various Fonts in 


figure 12. Display Format Tool 


the current Stack, Hypercard or your System File. You can 
sequence through all of the fonts one at a time or all at the same 
time using the Prev Font and Next Font buttons. Y ou can change 
or modify the text in the scrollable areas to see how it looks in 
various fonts. To restore the original text just click Restore Text. 
You can change the font size with the Change Font Size button. 

The Hide & Seek Tools allow you to see fields and buttons 
on cards and backgrounds even if they are hidden. This tool first 
allows you to scan to the card where the tool is to be installed. 

The Reorder Cards Tool allows you to reorder all ora portion 
of the cards in the current stack. This tool allows you to scan 
through various cards and select the order of each card by 
clicking on the card. 

The Order Info Tool allows you to see a list of all of the card 
field or card buttons. By selecting the appropriate buttons you can 
see an ordered list of all of the buttons or fields on the card or 
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figure 13. Visual Effects Tool figure 15. Sound Tool 
background. 

The Sort Lines Tool allows you to sort the contents of a 
scrollable field (or other multi-line field). Chicago 

HyperTools includes a built-in help function that lets you Io 
quickly get information on the different tools. To get help on any жон ыншы ыы nene Molte "ë 
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figure 16. View Font Tool 


figure 14. Group Tool 
tool on this screen, click on the help icon. Then click on any of Dx] Bk gnd Buttons 
the icons for the tools shown. _ 

In Summary the HyperTools package is а useful develop- DX Bkgnd Fields 


ment package for the novice anda timesaving device for the more 
experienced HyperProgrammer. 
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—Don Koscheka's XCMD Corner 

Last month I introduced XCMD programming. I explained 
the parameter block and discussed the interface between Hyper- 
Talk and the code that you write in either Pascal, “С” or the 
language of your choice. If you're an experienced Macintosh 
programmer, that's enough information to get started. The 
designers of HyperCard didn't stop with just defining the inter- 
face for you. They went beyond what might be reasonably 
expected and provided some HyperTalk programming capabili- 
ties to the XCMD programmer. The XCMD programmer gains 
access to these capabilities through callbacks. Callbacks are 
procedures and functions that you call from your XCMD. Call- 
backs literally jump into Hypercard to perform some function. 


Once you get the hang of XCMD programming, you'll come 
to rely on some of the callbacks quite frequently. For example, 
Pascal programmers are accustomed to strings that are preceded 
by a length byte and that have a maximum of 255 characters (the 
50255 type in Pascal) while HyperCard uses strings that have no 
length byte and are terminated with zero ( referred to as Zero- 
strings, zero-terminated strings or “С” strings). HyperTalk 
provides callbacks to convert from zero-terminated strings to 
Pascal and back again. The XCMD programmer can also use 
callbacks to retrieve and set the contents of fields and global 
containers as well as to send messages back to Hypercard. 


One of the reasons that this access to HyperCard containers 
is so important is that XCMDs do not have access to the 
application globals. When Hypercard starts up, it takes control 
of its application globals and heap justas any application would. 
With Hypercard in control of the heap, your XCMD becomes a 
"guest" of Hypercard. You don'thave access to the globals from 
your XCMD so you'll need a safe place to store information that 
you want to keep around. 


A good candidate is a global container. Although Hypercard 
itself prefers to see text strings in containers, it’s not particular 
about what you put into a container; you can use the SetGlobal 
callback to put data into a global container, and GetGlobal to 
retrieve that data. Make sure that you declare any global 
containers in Hypercard before accessing them in an XCMD. 
Your XCMD may need to be backward compatible earlier 
versions of Hypercard that bombed if you called SetGlobal with 

ап undeclared container name. 


An interesting example of the use of callbacks is to send a 


card message back to HyperCard from a callback. The XCMD 
in listing 1, “SendMeAMessage”, takes one parameter which is 
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the message to send back to HyperCard. Since messages are sent 
back as Pascal-format strings, we must convert the input string 
into a pascal string and then call SendCardMessage to send the 
message. As a matter of form, we set the return value to NIL 
indicating that this XCMD doesn’t have aresult code куре 
will interpret NIL as empty). 


The first callback that SendMeA Message invokes, ZeroTo- 
Pas, converts input parameter 1 from a zero-terminated string to 
a pascal-string. Input parameters are passed as handles so the 
parameter needs to be dereferenced one-time to convert the value 
to a pointer. ZeroToPas also expects you to pass a reference to 
the pascal-string into which you'll store the converted Pascal- 
string. The second callback, SendCardMessage, sends the 
message back to Hypercard. To invoke this XCMD from a script 
use the form: 


SendMeAMessage “ро next card” 


Because Hypercard already handles message passing, this 
XCMD may not seem terribly useful. Nonetheless, it isa good 
illustration of callbacks and the technique is useful if you need 
to alert the user that some asynchronous event has completed. 


(жежок) 
{* File: SendMeAMessage .p 


(йй. — E Á— 
(ЖЖЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ 
BUILD SEQUENCE 
CIGNORE LINK WARNINGS) 
pascal SendMeAMessage .p 
link -m ENTRYPOINT -rt XCMD=65534 9 
-sn Main=SendMeAMessage д 
SendMeAMessage.p.o à 
* (Libraries)^Interface.o д 
* (PLibraries)^Paslib.o д 


-о "(xcmds)^testxcmds 
ЖЖЖЖ 


($5 SendMeAMessage ) 
UNIT Donald. Ковсһека; 


( INTERFACE 
INTERFACE 


) 

USES MenTypes, QuickDraw, OSIntf, ToolIntf, 
PackIntf, HyperXCmd; 

PROCEDURE EntryPointC peramPtr: XCmdPtr); 

) 


(----ІМРІ ЕМЕМТАТІОМ 
IMPLEMENTATION 
($R-) 
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ТҮРЕ 
Str31 = StringI[311; 
PROCEDURE SendMeAMessageCparamP tr :XCmdP tr); 
FORWARD; 


( EntryPoint ү 

PROCEDURE EntryPoint(paramPtr: XCmdPtr); 
BEGIN 

SendMeAMessage(paramP {г ); 


D; 


( SendMeAMessage ) 
PROCEDURE SendMeAMessage(peremPtr: XCmdPtr); 
VAR 

theMessage : Str255; 


($I XCndGlue. inc ) 


BEGIN (*** Body of XCMD ***) 
ZeroToPas( paremPtr^.perems[1]^, theMessage ); 
SendCardMessage( theMessage ); 
paramPtr* .returnValue := NIL; 

END; (*** Body of XCMD ***) 

END. 


Listing 1. SendACardMessage 


XCMDs can also use callbacks to get the contents of a field 
or a global container. Listing 2, GetHomelnfo, uses two new 
callbacks (1) GetFieldByNum, to get the contents of background 
field 1 on the home card and (2) SetGlobal to set the contents of 
some global container. 


GetHomelInfo Takes one parameter, the name of the global 
container to set. First, convert the parameter to a pascal-string. 
Next, use a series of callbacks to push the current card and go to 
the home stack. Once we get to the home stack, we call 
GetFieldByNum to get field data. The first parameter that 
GetFieldByNum takes is set to TRUE if you want to retrieve the 
contents of a card field and set to FALSE to retrieve the contents 
of abackground field. The second parameter is the number of the 
field to retrieve. Alternatively, you could use GetFieldByID if 
you knew the id of the field or GetFieldByName if you knew the 
name. 


GetFieldByNum returns a handle to the zero-terminated 
data that was stored in background field 1 of the home card. We 
then invoke SetGlobal to set the contents of the global container 
to whatever is stored in fieldData. Finally, we pop the current 
card to get back to where we started. A typical invocation of this 
XCMD is: 


global myDeta 
GetHomeInfo “myData’ 


PROCEDURE GetHomeInfo(peremPtr: XCmdPtr); 


VAR 
globalName : Str255; 
fieldData : Handle; 
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($I XCmdGlue.inc ) 


BEGIN 
WITH peremPtr^ 00 
BEGIN 
7егоТоРаз( params[1]*, globalName ); 
SendCardMessage( “Push Card’ ); 
SendCardMessage( ‘Go Home’); 


fieldData := GetFieldByNumC FALSE, 1 ); 
SetGlobalC globalName, fieldData ); 


SendCardMessage( ‘Pop Card’); 
returnValue := NIL; 
END; 
END; 


Listing 2. Get Home Info. 


So far I’ve showed you XCMDs that don’t do anything that 
you can’t already do in HyperTalk. A key feature of XCMD 
programming is that you can write your own commands to 
augment or add capabilities to Hypercard. Listing 3, 
“FCreateXFCN”, lets you create a file of any type from Hyper- 
Card. This XFCN demonstrates how XCMDs provide greater 
access to the toolbox than is available to the HyperTalk script 
writer. 


FCreateXFCN introduces two new callbacks. NumToStr 
returns a result code to the script. NumToStr converts a signed 
long integer to a pascal-format string. If you don’t wanta signed 
entity, use LongToStr instead which will convert the long integer 
without regard to sign. 


The second callback introduced in this XFCN is PasToZero 
which takes a pascal format string and returns handle to a zero- 
terminated string. PasToZero is a handy way of copying from a 
pascal-string back to a zero-terminated string to return text to 
Hypercard. 


I wrote the XFCN in “C” to show the difference in formats 
between Pascal and “С” XCMDS and to provide a template for 
“С” programmers. An important difference is that the parameter 
list, params, starts at index 0 for “С” and index 1 for Pascal. 


FCreateXFCN first converts parameter 1 (params[0]) into a 
pascal-string and then moves the first four bytes of parameters 2 
and 3 into the variables creator and type respectively. These two 
variables are of type OSType which is a special Macintosh type 
containing four consecutive ASCII characters. All four charac- 
ters in this type are significant. 


The result code will be empty ifno error occurred and the file 
was created properly, otherwise it will return the OSErr number 
that occurred. First, convert the result code back to a pascal- 
string and then call PasToZero to convert that string intoa handle 
to a zero-terminated string. 
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The XFCN would be more useful if it returned a brief 
description of the error in English, but I think I'll leave that as an 
exercise for the student. Call FCreateXFCN with the following 
script: 


Put FCreateXFCNC “New File Мате”, "WILD^, “STAK” ) 


The first parameter is the name of the file you wish to create, 
the second parameter is the creator and the last parameter is the 
file type. The foregoing invocation will create an empty stack. 
What can you do with that? 


Гокка 
* file: FCreateXFCN.c 
x 


Жжжж ЖКЖ у 


/YXXXXXXX1XXXXXXXXXXXXXXXXXKXXET 


BUILD SEQUENCE 


С -q2 -g FCreateXFCN.c 
link -sn Main=FCreateXFCN à 
-sn STDIO=FCreateXFCN à 
-sn INTENV=FCreateXFCN à 
-rt XFCN=300 à 
-m FCREATEXFCN д 
FCreateXFCN.c.o à 
* (CLibreries)^CInterface.o à 
-0 testXCMDs 


ЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ KKK / 
#include «Турев.һ» 

"include <OSUtils.h»> 

"include «Memory.h»? 

"include <Files.h) 

"include «Resources.h? 
"include “HyperXCmd.h” 


pascal void FCreateXFCNC paramPtr ) 
XCmdBlockPtr paramPtr; 

/XXXXXXXXXXXXXXXXXXXXXXXXXXXX 

x In: Paramblock: 

х param[0] == filename 

х  parem[1] == TYPE 

х param[2] == CREATOR 


* Out: result code in returnValue 
POOOOOOOODORODOOOOOOOEROOOOEOEXOK / 


( 

char  *fname; 

05Туре type, creator; 
Str31 str; 


char — vNeme[33]; 
Short error, vRefnum; 


/** coerce the volume reference 
xxx 
*** number from the system 


xx / 
GetVolC vName, &vRefnum ); 


/** extract the filename from 
xxx 
*** the parameter list 

xx/ 


fname = *(рагатР4г-›рагатз [9 ]); 
BlockMove(*(paramPtr->params[ 1]),&creator , 4 ); 
BlockMove(*(paramPtr->params{2]),&type, 4 ); 
error = Create( fname, vRefnum, 

creator, type ); 
FlushVolC ØL, vRefnum ); 


ifC lerror ) 
paramPtr-?returnValue = ØL; 
else { 
NumToStr( paremPtr, Clong)error, &str ); 
paramPtr->returnValue = 
РазТойего( paramPtr, &str ); 


) 


8include <XCmdGlue. іпс.с› 


Listing 3. FCreateXFCN 


Although this article covered some of the more frequently 
used callbacks, my objective was to present you with the Spirit 
of the callback mechanism. You should have no trouble using 
any of the callbacks that are currently defined in the HyperCard 
Developer's ToolKit (available from APDA). The most impor- 
tant lesson here is that before you go off and write an XCMD, 
check the callback list to see how you might incorporate them 
into your XCMDs. Try to get the callbacks to do as much work 
as possible for you so that you can concentrate on the code that 
you are trying to write. 


Next Month: SortList, an XCMD that sorts a field by line. 


end HyperChat 


el 
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HyperChat™ 


Auto Hyper Edit Moves in Groups 


AutoHyperEdit 


Over the last few months we have seen the evolution of 
Hypercard Stacks. We have also been evolving AutoScriptEdit 
by showing you how to increase the functionality while retaining 
simplicity. I have had a lot of feedback about ASE and most 
people prefer it to the inbuilt shortcuts in Hypercard 1.2. 

So what was I to do for an encore, well I always wanted to 
group and move buttons etc. Souix Lacey did a great job with 
Groupies, and I wondered if I could make Hypercard act more in 
a Mac way. I decided to write AutoHyperEdit. 

Well I started experimenting and I was thoroughly addicted 
to solving the problem. Even half way throug writing it I thought 
it would be impossible to get around some obstacles that would 
make it work. The script basically allows the user to shift and 
click on objects to group them. The problem was if you clicked 
on a button for example after my stack had done it’s stuff it would 
then execute the button that was clicked on. So I couldn’t use nice 
things like target. The way I got around that was to check what 
objects were under the mouse at the time of the shiftKey. 

After I had the scripting finished I decided I would make a 
model Installer and Demo Stack. I will first take you through the 
Stack and then get into how and what was done. 
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figure 1. AutoHyperEdit 


The opening card shows what a little shading can do to add 
depth to your stack. The buttons I created to give as much 
feedback as possible. When you click on a button it appears to 
move in and the center black square turns to white. This is done 
by switching icons. Also to implement more feedback a click 
sound is heard. 

Ican'tstress the importance of a good user interface particu- 
larly in Hypercard. At least half of my time in this project was 
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spent on the interface. Apple is spending a lot of dollars on 
interface technology and have recognised the need for using it to 
aid in the smooth information flow between computer and 
machine. There is a group at Apple called the Human Interface 
Group, their sole job is to work on interface ideas and guidelines. 
If you have not read the Human Interface Guidelines do so 
immediately. It is a must. The guidlines are available through 
APDA and in some Bookshops and Computer Stores. 

If you go to the examples card you will see three new 
buttons; “Script Tools", “Object Tools" and “Aligning Tools". 
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figure 2. 


The Script Tools are the tools found in AutoScriptEdit-III. I 
use an interesting way to demo how the tools are to be used. There 
is part of a keyboard and part of a mouse pad and a mouse in the 
bottom left of the card, see figure 3. 
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figure 3. 
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When you click on a selection, you also get visual and 
auditory feedback, a field pops up along with two buttons; 
"Close" and "Show Me". 


Edit Field Script 


While holding the mouse 
button down on а field Ё 
move past the top of the fi: 
field. ji 


Try ít, or press 
"Show Ме“ for a Demo. 


figure 4. 


Clicking on “Show Me" Starts the demo. First the cursor 
dissapears and an icon that is identical to the cursor is shown at 
the point of interest. To attract the attention to the moving parts 
I flash" (hilite/unhilite) both the cursor and the the mouse icon. 
now I play the tune: 

play harpsichord tempo 1200 c5 c6 c7 

This signifies the start of what you should do. I then play the 
word “mousedown” which has been digitized. The icon changes 
showing a mouse with the button down. I showed the original 
demo's to non Mac users and they could follow how to do it 
easily. My previous tests where I didn't have all the feedback the 
user was a bit lost and did not know where to focus his attention. 
Therestof the demo shows the “mouse” and the “cursor” moving 
up above a field. The script editor is then evoked. 

The Object Tools shows buttons; “Grouping”, “Moving”, 
“Copying”, and “Clearing” see figure 5. 


figure 5. 
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The action of the buttons remain consistent even though the 
location is slightly different. One of the things to watch out for in 
your stacks is to keep consistency and simplicity at the forefront 
of your mind when you are designing. 

The demo of grouping shows the tool window first to show 
that you must be in the browse tool mode. You then click on an 
object with the shift key down. This will hilite a button. 
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figure 6 


There was a problem of not being able to hilite a field, so as 
well as a hilite I use a click tone. To select more objects just shift 
click again and to de-select you also shift click. Once you have 
finished selection you must double click not on an object. This 
will bring you to the button tool where you can choose a menu 
item such as "copy button". Or simply type command-C. I used 
afeature of Hypercard 1.2 to show the card picture. I have a menu 
as acard picture and I show капі drag a hilited transperent button 
toact as aregular menu, see figure 7. Now go to the card you want 
to paste to and do a command-V and the objects will appear. 
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Clearing objects works іп the same way, first selection then, 


double click, then menu command. 
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The next section is Aligning Tools. This allows you to select 
objects as before and then to hold down the mouse where you 
want the objects to be aligned, press the arrow key which 
ер to the bin das i.e. left arrow danda Е 
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figure 8. 


I also created an installer that puts the script into your home 
stack and adds a checkbox in the preferences card to allow you 
to turn AHE on and off. I do this in an interesting way. As well 
as the checkbox I add a hidden field to the card. I put the home 
stack into the field and search for specific comment strings that 
are on the same line as the handlers and I comment out the 
begining and end of the handlers. 


on mouseUp 
if the hilite of me is false 
then 
put the script of this stack 
lock screen 
show cd fld "TempAHE^ 
repeat 8 times 
set cursor to busy 
find *—**AutoHyperEdit**-^ 
put the foundline into temp 
select temp 
put *-" before the selection 
put the selection into temp 
end repeat 
set script of this stack to cd #19 "TempAHE^ 
put empty into cd #19 "TempAHE^ 
hide cd #19 “ТетрАНЕ” 
unlock screen 
else 
put the script of this stack 
lock screen 
show cd fld "TempAHE^ 
repeat 8 times 
set cursor to busy 
find *—**AutoHyperEdit**-^ 
put the foundline into temp 
select temp 
put the selectedtext into stext 
delete cher 1 to 2 of stext 
put stext into the selection 
put stext into temp 
end repeat 
set script of this stack to cd fld “ТепрАНЕ” 
put empty into cd fld "TempAHE^ 
hide cd fld “TempAHE” 
unlock screen 


into cd fld “ТетрАНЕ” 


into cd #19 “ТетрАНЕ” 
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end if 
end mouseUp 


The Remove card simply removes all traces of AHE. 


Hereisthe scriptI will go through the important parts and tell 


you what they do. 


— AutoHyperEdit 1.0 by Fred Stauder June 1988 — 


- Put this Script into your Home Stack 
- To use keep mouse btn down over Button or Field and move mouse 


up 


- To edit Bkgnd Script keep mouse btn down move mouse to -left 


of card 


- Card Script - move right 

- Stack Script - move up 

- Now works with unlocked fields 

- To lock and unlock fields option click in them 

- To show/hide tools/patterns at cursor 

- hold option click on non-field areas 

— click in top left to hide cd window botom right to show 

-Group objects by shift clicking in browse tool 

-Моуе objects by holding mouse down and draging 

-Сору and Clear groups of objects after selecting by using 
menus 

— Align objects after selecting, hold mouse down at align loc 
and press 

— the arrow key i.e. align left use left arrow key 

— Turn АНЕ on and Off using the Checkbox installed in the Pref 
Card of Home 


The globals are CWSlist is where the selected objects id’s 
are cwloc is the card window location to hide the card and 
selectcomp is a flag for when the selections are compleated. 

Gobo resets the hilites and puts empty into CWSList. The 
first section is AutoScriptedit Stuff. 


on mouseStillDown —**AutoHyperEdit**- 
Global cwslist,cwLoc, selectcomp 
if selectcomp is “true? then gobo 


put empty into CWSList 


if the optionkey is down 
then 
if the target contains “field” then set locktext of target 
to false 
else 
if the optionkey is down then 
set the visible of pattern window to not the visible 
of pattern window 
set the loc of pattern window to the mouseloc 
set the visible of tool window to not the visible of 
tool window 
set the loc of tool window to the mouseloc 
exit mouseStillDown —— 
end if 
end if 
end if 
if the mouseloc is within “8,0, 10, 10" 
then 
put the loc of card window into CWLoc 
set loc of card window to -504,-315 
exit mousestilldown 
end if 
if the mouseloc is within “500,333,512,346* 
then 
set loc of card window to CWLoc 
exit mouseStillDown 
end if 
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put char 6 of the target into C6 

if C6 is quote then AutoScriptEdit 

if C6 is “i? then AutoScriptEdit 

if Сб is quote then exit mousestilldown 

if C6 is “i” then exit mousestilldown 

if the mouseV <item 2 of rect of target then edit script of 


put empty into foundit 
put false into offdetected 
if cwslist is empty 
then 
if the shiftkey is down 
then 
repeat until offdetected is true 
if the shiftkey is down 
then 
shiftselect 


Here we go to the routine that selects objects. 


put false into foundit 
else 
movegroup 
wait until the mouse is down 
repeat with y = the number of items in CWSlist down 
to 1 
if the mouseloc is within the rect of item y of 
cwslist 
then 
put false into foundit 
exit repeat 
else 
put true into foundit 
end if 
end repeat 
end if 
if foundit is true 
then if the shiftkey is up then put true into 
offdetected 
end repeat 


choose btn tool 
select item 1 of cwslist 
put “true” into selectcomp 
end if 
end if 
end if 
-pass mouseStillDown 
end mouseStillDown —**AutoHyperEdit**- 


on AutoScriptEdit 
if the mouseH « 2 then edit script of this bkgnd 
if the mouseH > 510 then edit script of this card 
if the mouseV < 2 then edit script of this stack 
end AutoScriptEdit 


on openfield —**AutoHyperEdit**— 
if the optionkey is down 
then 
if the mouseV «item 2 of rect of target 
then 
edit script of target 
set locktext of target to false 
exit openf ield 
end if 
set locktext of target to true 
end if 
pass openfield 
end openfield —**AutoHyperEdi t**— 


This traps the menu selections so that copy buttons etc will 
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work on groups of objects 


on domenu stuff —**AutoHyperEdit**- 
global WhatsMyCardName, CWSL ist, selectcomp 
if selectcomp is true 
then 
if stuff is “clear button” 
then 
clrobj 
exit domenu 
else if stuff is "Copy Button” then 
put the long name of this card into WhatsMyCardName 
pass domenu 


else if stuff is "cut button^ then put tip into top 
else if stuff is "peste button” then 
pasteobj 
exit domenu 
else if stuff is “Copy field’then 
put the name of this card into WhatsMyCardName 
pass domenu 
else if stuff is "paste field” then pasteobj 
else if stuff is "clear field" then clrobj 
pass domenu 
exit domenu 
end if 
pass domenu 
end domenu —**AutoHyperEdi t**- 


This is the Object clearing routine. 


on clrobj 
global CWSL ist 
lock screen 
repeat with р= the number of items in CWSlist down to | 
set cursor to busy 
put item p of CWSlist into it 
select it 
type “x” with commandkey 
end repeat 
choose browse tool 
unlock screen 
put empty into Cwslist 
end clrobj 


This is the object pasting routine 


on pasteobj 
global CWSL ist, WhatsMyCardName , selectcomp 
put false into selectcomp 
set lockscreen to true 
set lockmessages to true 
repeat with x» the number of items in CWSlist down to 1 
if second word of item x of CWSList ~ 
is *field^ then choose field tool else choose btn +001 
set cursor to busy 
push card 
go to WhatsMyCardName 
put item x of CWSlist into it 
if second word of it is “btn” then set hilite of it to false 
if first word of it is “btn” then set hilite of it to false 
select it 
type "c^ with commandkey 
pop card 
if first word of it is "Bkgnd" then type “b” with cmdkey 
type "v^ with commandkey 
if first word of it is “Вкопа” then type "b^ with cmdkey 
end repeat 
choose browse tool 
set lockscreen to false 
set lockmessages to false 
put empty into CWSlist 
put empty into WhatsMyCardName 
put false into selectcomp 
choose browse tool 
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end pasteobj 


on gobo 
global CWSList, turnoff ,selectcomp 
repeat with х= the number of items in CWSlist down to 1 
if second word of item x of CWSList is "btn^ then set the 
hilite of item x of CWSlist to not the hilite of item x of CWSlist 
if first word of item x of CWSList is “btn” then set the 
hilite of item x of CWSlist to not the hilite of item x of CWSlist 
end repeat 
put empty into CWSList 
end gobo 


Here I had to test for different objects. I tried to put “if the 
mouseloc is within the rect of a variable then..." where the 
variable contained an objuct such as btn and another variable. 
This did not work it is a pity I could have cut the script down 
considerably. Because of this I have to handle the object types 
seperately. 


on shiftselect 
global CWSlist,w,x,y,z 
repeat until the shiftkey is up 
repeat while the mouse is down 
repeat with w = the number of cd btns down to 1 
if the mouseloc is within the rect of btn w then 


HITCBtn 
end repeat 
repeat with x = the number of bkgnd btns down to 1 
if the mouseloc is within the rect of bkgnd btn x then 
HITBBtn 
end repeat 
repeat with y = the number of cd Ғ105 down to 1 
if the mouseloc is within the rect of cd fld y then 
НИТСЕ19 
| end repeat 
repeat with z = the number of bkgnd flds down to 1 
; if the mouseloc is within the rect of bkgnd fld z then 
HITBF1d 
end repeat 
end repeat 
end repeat 


end shiftselect 


on HitBF1d 
global CWSlist,z 
put false into foundit 
if the commandkey is down then set the visible of bkgnd fld 
z to not the visible of bkgnd fld z 
if the number of items in CWSlist =0 
then 
put “Bkgnd field id ~ & the id of Bkgnd fld z & *,"after 
CWSList 
play harpsichord tempo 100 b8x7 
exit HitBFld 
end if 
repeat with p = the number of items in CWSlist down to 1 
put item p of CWSList into it 
if it = "Bkgnd field id ” & the id of Bkgnd fld z 
then 
delete item p of CWSList 
play harpsichord tempo 100 р8х7 
exit HitBF1d 
end if 
end repeat 
put “Bkgnd field id ~ & the id of bkgnd fld z & ","efter 
CWSL ist 
play harpsichord tempo 100 b#x7 
end HitBF ld 


on HitCFld 
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global CWSlist,y 
put false into foundit 
if the commandkey is down then set the visible of cd fld y 
to not the visible of cd fld y 
if the number of items in CWSlist =0 
then 
put “Card field id ” & the id of cd fld y & *, “after CWSList 
play harpsichord tempo 100 bx] 
exit HitCFld 
end if 
repeat with р = the number of items in CWSlist down to 1 
put item p of CWSList into it 
if it = “Card field id “ & the id of cd fld у 
then 
delete item p of CWSList 
play harpsichord tempo 100 b8x7 
exit HitCFld 
end if 
end repeat 
put “Card field id ~ & the id of cd fld y & %, “after CWSList 
play harpsichord tempo 100 bfx7 
end HitCFid 


on HitBBtn 
global CWSlist,x 
put false into foundit 
if the commandkey is down then set the visible of bkgnd btn 
x to not the visible of bkgnd btn x 
set the hilite of bkgnd btn x to not the hilite of bkgnd btn 


X 
if the number of items in CWSlist -0 
then 
put “окота btn id 4% the id of bkgnd btn x & *,"after 
CWSL ist 


play harpsichord tempo 100 bx] 
exit hitBBtn 
end if 
repeat with p = the number of items in CWSlist down to 1 
put item p of CWSList into it 
if it = "bkgnd btn id 4% the id of bkgnd btn x 
then 
delete item p of CWSList 
play harpsichord tempo 100 b#x7 
exit hitBBtn 
end if 
end repeat 
put “bkgnd btn id * & the id of bkgnd btn x & *,"efter CWSList 
play harpsichord tempo 100 08х7 
end HitBBtn 


on HitCBtn 
global CWSlist,w 
put false into foundit 
if the commandkey is down then set the visible of btn w to 
not the visible of btn w 
set the hilite of btn w to not the hilite of btn w 
if the number of items in CWSlist =Ø 
then 
put “btn id 4 & the id of btn w & ","efter CWSList 
play harpsichord tempo 100 bx] 
exit hitCBtn 
end if 
repeat with p = the number of items in CWSlist down to 1 
put item p of CWSList into it 
if it = “btn id "^ & the id of btn w 
then 
delete item p of CWSList 
play harpsichord tempo 100 b*x7 
exit hitCBtn 
end if 
end repeat 
put “btn id 4 & the id of btn ий", “after CWSList 
play harpsichord tempo 100 bx] 
end HitCBtn 
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This section moves the objects. 


оп movegroup 
global CWSList 
wait until the mouse is down 
put the mouseLoc into mLoc 
put empty into mH 
put empty into mV 
repeat with i = 1 to the number of items in CWSList 
put item i of CWSList into iList 


put item 1 о? the loc of iList - item 1 of мос & “,” after 


mH 


put item 2 of the loc of iList - item 2 of тос & “,” after 


mV 
end repeat 
repeat while the mouse is down 
get the mouseLoc 
lock screen 
repeat with i = 1 to the number of items in CWSList 
put it into iList 
add item i of mH to item 1 of iList 
add item i of mV to item 2 of iList 
set loc of item i of CWSList to iList 
end repeat 
unlock screen 
end repeat 


end movegroup 


I added this section very quickly because I already had the 
underlying selection and moving structures. As you can see it is 
very simple. 


on arrowkey whichkey 
global CWSList 
if the mouse is down then 
if whichkey = “left” then 
put the mouseH into L 
repeat with 1 = 1 to the number of items in CWSList 
put the width of item i of Cwslist into w 
set the left of item i of Cwslist to L 
set the width of item i of Cwslist to w 
end repeat 
end if 


if whichkey = “right” then 
put the mouseH into R 
repeat with i = 1 to the number of items in CWSList 


put the width of item i of Cwslist into w 
set the right of item i of Cwslist to R 
set the width of item i of Cwslist to w 
end repeat 
end if 


if whichkey = “up” then 
put the mouseV into T 
repeat with i = 1 to the number of items in CWSList 
put the height of item i of Cwslist into h 
set the top of item i of Cwslist to T 
set the height of item i of Cwslist to h 
end repeat 
end if 


if whichkey = “down” then 
put the MouseV into B 
repeat with i = 1 to the number of items in CWSList 
put the height of item i of Cwslist into h 
set the bottom of item i of Cwslist to B 
set the height of item i of Cwslist to h 
end repeat 
end if 
exit arrowkey 
end if 
pass arrowkey 

end arrowkey —*AutoHyperEdittt- 

Non-Comercial use only - All Rights Reserved 

Fred Stauder, Hypercard Editor, (HyperChat) MacTutor 

---- AutoHyperEdit by Fred Stauder, June 1988 --- 

You should get the stack because of the animation and sound 
ideas it contains. The key thing is to plan your stacks keep them 
modular so that they can be added to and be polite and use the pass 
statement so that other peoples scripts will work. For example a 
stack that uses on mouseStillDown and does not pass it will stop 
AutoHyperEdit working in that Stack. 

Send your Articles, ScriptTips, SpeedTips, etc. to: 

Fred Stauder, AppleLink D0280 

Ecofin Reseach and Consulting 

Lavaterstrasse 45 

Zurich 8002 

Switzerland 

or 


To the MacTutor Office 


T 
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HyperChat™ 


XCMD Cookbook: Sorting Routines 


In the last two issues we covered XCMD programming 
basics. First we looked at the interface between Hypercard and 
ХСМ and then we discussed the callbacks and how they can 
make your XCMD programming a little easier. This month, I 
present an XCMD that adds a useful feature to Hypercard - the 
ability to sort lines in a text field. 

This is a good example of XCMD programming since it 
extends Hypercard by adding anew feature. In addition to adding 
features, XCMDs are a useful way of speeding up some process 
that may have been written in HyperTalk. Sorting lines of text is 
certainly something that could be accomplished in Hypertalk. 
Butif you have alot of lines in the field, the Hypertalk script may 
be too slow. Enter the XCMD! 

Before we can write the sort program, we must decide what 
itis we want to sort and what form the data will be presented in. 
Let's define a line as a string of text that is spearated by a newline 
character. Next we'll want to be able to sort both alphabetic 
strings and numeric strings. We need the numeric sort because 
strings of characters are sorted by ASCII value rather than 
numeric value. 

Once we decide on the form and value of the data to sort, we 
can decide what we need to pass to the XCMD from Hypercard. 
Obviously, we'll need the lines. Parameter 1 will contain a 
handle to the field, parameter 2 will tell the XCMD whether to 
sort by ASCII value (alphanumeric sort) or by numeric value 
(decimal sort). Parameter 3 tells the xcmd to sort in ascending or 
descending order. Actually LineSort only sorts in ascending 
(smallest to largest) order. There really is no need to sort from 
largest to smallest. You can simply report the lines “backwards” 
to get descending order. I've left this as an exercise to the reader 
since it involves little more than reversing the order of the FOR 
loop in two of the routines in SetNewText and SetNewNums. 

WhenLineSort is complete, we'll return the sorted list in the 
parameter block'sreturnValue. By making this an XFCN wecan 
invoke it using the follwing format: 


Put LineSort( card field “my list”, alpha ) into card field 
"my list’ 


The actual process of sorting can be broken down into the 
following steps: 
(1)LineStart: Create an array of offsets into the list marking the 
start of each line. 
(2) SortText: Sort the list of text by comparing lines using some 
sorting algorithm. 
(3) SetNewText Report the sorted list back to Hypercard. 


(Note: the process is identical for numeric sorting. Because 
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the numeric sort is quite a bit simpler in implementation, we'll 
concentrate this discussion on the text sort). 

How we accomplish these three tasks is quite another story. 
Sorting lines of text is not as straightforward as sorting integers 
or characters since each line can be of an arbitrary length. Before 
performing the sort, we need to calculate where in the large chunk 
of text each line starts. We create an array, LineStart, that gives 
us an offset into the list of the start and length of each line. 
Consider the list: 


Margaret 
Colleen 
Donald 


The first line in the list has an offset of 0 and a length of 8. 
The next item in the list has an offset of 9 and a length of 7. The 
third item has an offset of 17 and a length of 6. If the numbers 
don't seem to add up it's because the linestart array accounts for 
the newline character that terminates every entry in the list! 

This matter of creating a linestart array pays handsome 
dividends. When it comes time to sort the list, we don't have to 
move the strings around in memory. Rather, we simply rearrange 
the linestart array to reflect the sort order. For example, the line 
start array for the above array looks like this before the sort: 


[0,8] 

[9,7] 

[17,6] 

and like this after the sort: 
[9,7] 

[17,6] 

[0,8] 


To report the sorted list back to hypercard now becomes a 
simple task. SetNewText extracts N elements from the linestart 
аттау where М is the number of elements in the array. We 
determine this number by dividing the size of the array by the size 
ofoneelementin the array. Foreach elementin the array, the first 
value in the array is the offset of the first byte in the string and the 
second element is the number of bytes to copy onto that line. 
Each line is already terminated with a newline so the process of 
building the output string is a simple process of concatenating the 
strings in the order prescribed by LineStart. If you want to 
perform a descending sort, build the output list starting with the 
last element in the array and work your way backwards, one 
element at a time! This is good practice for the beginner so I 
haven't included the sort order part of the code. 
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I glossed over the actual sorting of the linestart array for two 
reasons. First off, it looks a lot scarier than it is. Second off, you 
may want to replace my sorting algorithm with one of your own. 
I use a Shell sort because it is one of the easier sorting methods 
to follow. If you're programming in MPW “С” you should 
consider replacing SortText and SortNums with Apple's Quick- 
erSort. Greg Kimberly of Apple Computer, Inc. demonstrated an 
XCMD to me that uses QuickerSort. It was at least three times 
faster than my Shell sort implementation! 

The Shell sort starts by comparing the first element in the 
array with every element thatis at least jump elements away from 
the first element. If an some element is smaller than the first 
element, then we swap that element, and test the next one. Once 
no more elements can be swapped, we exit the FOR loop, 
decrease the jump size and start the comparison process all over 
again. 

The ToolBox call IUMagString compares the two string 
elements and returns -1 if string 1 is less than string 2, 0 if they're 
equal and 1 if string 1 is greater (the swap condition). IUMag- 
String takes two string pointers and the length of each string as 
input. The length is easy, that's simply the second element of 
each linestart array entry. We can create a pointer to each line by 
adding the offset element of each array entry to the starting 
address of the text. Since the text is referenced via a handle 
(passed to sortText as hField), we lock down the handle to make 
sure that this starting address doesn't change on us during the 
sort. 

The numeric sorting scheme is very similar to the alpha 
scheme, only easier because the size of each element is fixed at 
4 bytes (the size of alongInt). If you have trouble reading the sort 
Text routines, try starting with the sort numeric code. 


Next month: File ПО. You can take it with you! 


(oocoocooecoooepeoocoooeoeeer) 


(* File: LineSort.p x) 
x x) 
(* Sorts lines of text (delimited by *) 
(* newline and null terminated). *) 
(* Returns the sorted container. *) 
Х.........-----------.---.....-.--- x 

(* In:  paremPtrspointer to the XCMD х) 
(* Parameter Block *) 
(* x) 


(* params[1] = handle to the text 5%) 
(ж params[2] = handle to sort type *) 


(* (АРНА, NUMERIC) x) 
(* рагатѕ [3] = Sort Order х) 
(ж CASCENDING, DESCENDING) x) 
(* x) 
(* Defaults : ALPHA, ASCENDING x) 
(* Out: returnValue = h endle to the *) 
(ж sorted data x) 
(* x) 
(-- x) 

(* € 1988, Donald Koscheka 5) 
E А11 Rights Reserved x) 
Xl-—————— ÓÁ— U U x 


(ocooooooooooooooooooooorg) 


(ЖЖЖЖ 
BUILD SEQUENCE 
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pascal LineSort.p 

link -m ENTRYPOINT -rt XFCN=65535 д 
-sn Main=LineSort д 
LineSort.p.o 9 
* (Libreries)^Interface.o д 
* (PLibreries)^Paslib.o à 
-0 "(xcmds) ^testxcmds 


ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖЖ 
($8 LineSort ) 
UNIT Donald Козсһека; 


(—— INTERFACE 
INTERFACE 
USES 


MemTypes, QuickDraw,OSIntf , ToolIntf, 
PackIntf , HyperXCmd; 


) 


PROCEDURE EntryPoint(paramPtr :XCmdPtr); 
(——IMPLEMENTATION——) 


IMPLEMENTATION 

($R-) 

CONST 
NULL = $00; 
NEWL INE = $00; 
ALPHA = $00; 
NUMERIC - $01; 
ASCEND = $00; 
DESCEND = $01; 
LESSTHAN = -1; 
EQUALTO - 0; 
СКЕАТЕКТНАМ = 1; 

ТУРЕ 
Str31 = StringI[311]; 
LinePtr = ^LineElem; 
LineHand = “LinePtr; 
LineElem = PACKED RECORD 

Start : LongInt; 
Size: LongInt; 

END; 
numPtr = “LongInt; 
numHand = “numPtr; 


PROCEDURE LineSort(paramPtr :XCmdP tr); 
FORWARD; 


(— ——EntryPoint 


) 
PROCEDURE EntryPoint(paramPtr: XCmdPtr); 
BEGIN 


LineSort(paramP tr); 
END; 


(——-ineSort ) 


PROCEDURE L ineSortCparamPtr :XCndPtr); 
(QOOOOOOEEEXXGOOEOROUEEOROOEOEOROKK 


* Main code segment follows 
XOOOOOOOOEOECEGEOOGEOOOEEE EX XC) 


VAR 
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SortType : INTEGER; 
Sor tOrder : INTEGER; 
LineStart : LineHand; 
hNums : numHend; 
NewF ield : Hendle; 
SortStr : $tr255; 


($I XCmdGlue. inc ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ® ) 


(*** Alpha Sorting Routines 


xxx) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ xx ) 


FUNCTION GetLineStartsChF ield:Handle) 


: LineHand; 


(ЖЖЖЖЖЖЖЖЖЖЖЖ ХХХ ХА ХХХ ХХХ 


x 
x 
x 
x 
x 
x 
* 
* 
* 
* 
x 
x 
x 
x 
x 
x 
x 
x 
* 
* 


Given 8 pointer to а block of text, 
scan Гог line-terminators CNEWLINE 
| NULL) and fill out a dunamicallu 
allocated arrau of line starts 
information. 


The line starts arrau contains 

the offset in the text to the start 
of the line as well as the length 
of the line in butes. 


Offsets are used to allow the гесогд 
to remain valid across relocation 
of the basic text. 


In: Pointer to a block of text, 
null terminated. 


Out: Hendle to en array of 


linestert indices. 
x 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖАЖЖЖЖЖЖ)) 


ҮАК 


txStert : Ptr; ( pointer to the input text) 

txPtr : Ptr; ( pointer into input text (FIELD) 

lineArray: LinePtr; ( Pointer into lineStart array ) 
BEGIN 

IF (hFieldONILDANDChF ield^^ O NULLOTHEN 

BEGIN 

HLockC hField 2; 

txPtr := hField^; 

stertText := ORDC txPtr ); 

lineStart := LineHandC(NewHandle(C2)); 

done := FALSE; 


done : BOOLEAN; 
erreySize: LongInt; 
stertText: LongInt; 
sizeText : LongInt; 
lineStart: LineHend; 


( Base pointer of the text ) 
( length of the current run) 
( erray of lineSterts pointers) 


WHILE NOT done DO 

BEGIN 
txStert := txPtr; 
ScanToReturn( txPtr 2; 


IF txPtr^ = NULL THEN 
BEGIN 
txPtr^ — :- NEWLINE; 
done := TRUE; 
END; 


txPtr := PointerC ORDCtxPtr) + 1); 
sizeText :- ORDCtxPtr2-ORDCtxStart?; 
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END; 


IF sizeText > 1 THEN 
BEGIN 
(*** point to next record іп linestarts array ***) 
erraySize := GetHendleSizeC Hendle(LineStart) 2; 
SetHendleSizeC Handle(LineStart), 

arraySize + sizeOf( lineElem )); 
lineArray := Pointer( ORDClineStart*) + arraySize 2; 


(*** Put away offset and length of line ***) 
WITH 11пеАггау^ 00 
BEGIN 
Start:= ORDCtxStart) - startText, 
Size := SizeText; 
END; 


END; 
END; (*** While **x) 


HUnlock( hField ); 
END; 


GetLineStarts := lineStert; 


PROCEDURE SortText( hField:Hendle 2; 


(YXXXXX1XXXXX1XXXXXXXX5X5XX 

* Given a handle to an run of text, 
sort the lines of text pointed to and 
геаггапде the arrau accordinglu. 


Text is sorted bu rearranging the line 


In: 


Out: 


* 
x 
x 
x 
* sterts аггау. 
x 
x 
x 
x 


Pointer to array of linestarts 
linestarts, linecount (global) 
sorted array of linestarts. 


EXXKAKKAAKAAKE ЖЖ XX) 


VAR 


done : BOOLEAN; 
jump, 1еп1, 1еп2: INTEGER; 
n,m,lineCount : LongInt; 


stri, str2 : Ptr; 
tempElem : LineElem; 
elemi, elem2 : LinePtr; 

BEGIN 
LineCount = GetHendleSizeC HandleClineStart) 2; 
LineCount ‚= LineCount DIV sizeOfC LineElem ); 
jump := lineCount; 


HLockC HandleClineStart) 2; 
HLockC hField ); 


WHILE jump > 100 


BEGIN 
jump := jump DIV 2; 
REPEAT 
done :- TRUE; 
FOR m := Ø to С lineCount - jump - 1 > DO 
BEGIN 


n := m + jump; 


(жж Calculate the offsets of the two elements ***) 
elem! := LinePtrC ORDCLineStart*) + 
(n * sizeof( LineElem 2) 2; 


stri := PointerC ORDC hField^ ) + eleml1^.Staert) ; 
]еп1:= INTEGERC elemi^.Size 2; 


‚= LinePtrC ORD(LineStart*) + 
(m * sizeof( LineElem )) 2; 


elem2 


str2 := PointerC ORDC hField^ ) + 
elen2^.Start) ; 
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Теп2 := INTEGERC elem2*.Size ); 


IF IUMagString( str2, stri, len2, leni ) 

= GREATERTHAN THEN 

BEGIN 
tempElem.Start := elem1^.Start; 
tempElem.Size := eleml^.Size; 
elemi* Start := elem2^.Start; 
elem1^.Size := elem2* .Size; 
elem2° Start := tempElem.Start; 
elem2* .Size ‚= tempElem.Size; 
done := FALSE; 


END; 
END; (*** FOR loop ххх) 
UNTIL done; 
END; (*** WHILE jump > 1 ***) 


HUnlockC HandleClineStart) ); 
HUnlockC hField ); 
END; 


FUNCTION SetNewText( hField: Handle; 
Dir : INTEGER 2: Handle; 
( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
* Given а pointer to a linestarts array, and 
* а corresponding block of text, rearrange 
* the text to match the line starts in the 
* аггау. This is useful after doing а search 
since the linestarts array will be in order 
but the text won't be. 


ж 


return a run of null-terminated text 
with each line NEWLINE-terminated. 


x 
x 
x 
x 
x 
* In: Handle to text array 

x Handle to linestarts array. 
x 


* Out: Handle lines of newline terminated text. 
XKXXXXXXXXXXXXXXXXXXXXXXXXXX) 


VAR 
LineNum, 
LineCount, 
oldSize : LongInt; 
NewText : Handle; 
Star t0fLine : Ptr; 
NextLine : LinePtr; 
BEGIN 
LineCount := GetHandleSizeC HandleClineStart) ); 
LineCount := LineCount DIV sizeOf( LineElem ); 
NewText := NewHandle( Ø ); 


FOR LineNum := 0 to LineCount-1 DO 
BEGIN 
NextLine := LinePtrC ORDC LineStart^ ) + 
(LineNum * sizeOfC LineElem )) ); 
StartOfLine := PointerC ORDC hField^ ) + 
NextLine^.Start ); 


(*** add length of new line to output text ххх) 
oldSize := GetHandleSizeC NewText ); 
SetHandleSizeC NewText, oldSize + NextLine^.Size ); 


(*** move the line into the array ***) 
BlockMoveC StertOfLine, Pointer( ОВОС NewText^ ) 
+ oldSize), NextLine^.Size ); 
END; 


(*** Tack а NULL on the end of the new text ***) 


oldSize :- GetHandleSizeC newText ); 
SetHendleSizeC newText, oldSize + 1 ); 
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StertOfLine :- PointerC ORDC newText^ ) + oldSize ); 
StartOfLine^ := NULL; 
SetNewText - NewText; 


END; 


(ЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


(*** Number Sorting Routines ххх) 
б 222 252222222123 


FUNCTION GetNumsC hField : Handle ): numHand; 


(ЖЖЖЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
* Given а hendle to a block of text, scan 


_ * for line-terminators (NEWLINE | NULL) and 


* fill out а dynamically allocated array of 
* long integers, one for each line. 
x 


х Out: Handle to an array of longInt. 


x 
XXXXXXXXXXXXXXXXXXXXXX1XXXX) 
VAR 
done : BOOLEAN; 
arrauSize, 
theNum  : LongInt; 
txStert : Ptr; 
txPtr : Ptr; 
numArray : numPtr; 
hNum : NumHand; 
tStr : Str255; 
BEGIN 


IF C hField © NIL ) AND € hField** o NULL > THEN 
BEGIN 

HLockC hField ); 

txPtr ‚= hField*; 

hNum := NumHand( NewHandle( Ø ) ); 

done :- FALSE; 


WHILE NOT done DO 

BEGIN 
txStert := txPtr; 
ScanToReturn( txPtr ); 
IF txPtr^ = NULL THEN 

TRUE 


txPtr^ := NULL; 


ГегоТоРаѕ( txStart, tStr ); 
theNum := StrToNum( tStr ); 
txPtr := Pointer( ORDCtxPtr) + 1); 


erraySize := GetHandleSizeC HandleC hNum ) ); 

SetHandleSizeC HandleC hNum ), arraySize + 
sizeOfC longInt 2); 

numArray := Роіпбегі ORDC hNum^) + arraySize ); 

numArray*:= theNum; 


END; (*** While ххх) 
HUnlockC hField ); 
END; 
GetNums := hNum; 
END; 


PROCEDURE SortNums( theNums : 
2229222222229 ХХХ ЖЖ 

* Given a pointer to ап array of longints, 
* sort the numbers and rearrange the array 
accordingly. 


NumHand ); 


x 
x 
* In: Handle to an array of longInts; 
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* uses linecount and lineNum; 
* Out: sorted array of linestarts. 
KXXKKKKKKKKAAAAKAKAKKE ) 
VAR 
done : BOOLEAN; 
jump, len1, len2 : INTEGER; 
n,m ,Swep, 
lineCount 
num1,num2 


: LongInt; 
: numPtr; 


BEGIN 

LineCount := GetHandleSizeC HandleCtheNums) ) DIV sizeOfC 
LongInt 2; 

jump := lineCount; 


WHILE jump » 100 
BEGIN 
jump := jump DIV 2; 
REPEAT 
done :- TRUE; 
FOR m := 0 to С lineCount - jump - 1 2 DO 
BEGIN 
n := m + jump; 


(*** Calculate the offsets of the two elements ***) 
пит1:= Pointer CORDCtheNums^) + Сп * sizeof ¢ 
LongInt 22 2; 
num2 := Pointer CORDCtheNums^) + (m * sizeof( 
LongInt 22 5; 


IF num2^ > numi* THEN 


BEGIN 
swap := numl1^; 
num 1^:= num2^; 
num2*:= swap; 
done := FALSE; 
END; 


END; (*** FOR loop ***} 
UNTIL done; 
END; (*** WHILE jump > 1 ***) 
END; 


FUNCTION SetNewNumsC hNum: numHand; Dir 
622225524222222222 XX 


х Given а handle to an array of 

* longints, convert them back to 
* strings and put them away in 

х а new handle as text 
x 
x 
x 


: INTEGER ): Handle; 


In: Handle to num array 


* Out: Handle lines of newline 
* terminated text. 
XXXXXXXXXFXXXXXXXXXXXX) 
VAR 

index, intCount, 


oldSize, numLen LongInt ; 

nexNum NumP tr ; 

NewText Handle; 

tempPtr : Ptr; 

tempStr : $tr255; 
BEGIN 

NewText := NewHandle( 0 ); 


intCount := (GetHandleSizeC HandleChNum) 2 DIV sizeOfC 
LongInt 22; 


FOR index := 8 to intCount-1 DO 
BEGIN 
‚= NumPtrC ORDC hNum^ ) + 


(index * sizeOf(C LongInt 2) ); 
tempStr := NumToStr( nexNum^ ); 


nexNum 
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помел := LongIntC ORDC tempStr[2] ) 2; 

(*** add length of new line to output text  ***) 
oldSize := GetHandleSizeC NewText 2; 
SetHendleSizeC NewText, oldSize + NumLen + 1 2; 


(*** move the line into the array xxx) 
TempPtr := PointerC ORDC @tempStr ) + 1 ); 
BlockMoveC TempPtr , PointerCORDC NewText*)+ 
oldSize),NumLen); 
TempPtr := PointerCORDC NewText*) + oldSize + 
Миті еп); 
' TempPtr^ := NEWLINE; 


2 


(*** Tack а NULL on the end of the new text ***} 
oldSize ‚= GetHandleSize( newText ); 
SetHandleSize( newText, oldSize + 1 2; 


tempPtr ‚= PointerC ORDC newText^ ) + oldSize ); 
TempPtr^ ‚= NULL; 
SetNewNums ‚= NewText; 


END; 


(****zxzz Main Block for LineSort **txxxx) 
BEGIN 
NewF ield := NIL; 


WITH paremPtr^ DO 
IF Cparams(1) <> NIL) AND (рагатз[1]-^ © NULL) THEN 
BEGIN 
SortType := ALPHA; 
SortOrder := ASCEND; 


IF рагатз[2] © NIL THEN 
BEGIN 
ТегоТоРавС рагатз[2]^, sortStr ); 
IF StringEqualC^NUMERIC^, sortStr) 


THEN 
SortType := NUMERIC; 
END; 
IF params(3) © NIL THEN 
BEGIN 


ТегоТоРавС parems(3]^, sortStr 2; 
IF StringEqual( ‘DESCENDING’, 
sortStr 2 THEN | | 
SortOrder := DESCEND; 
END; 


CASE SortType OF 
ALPHA: 
BEGIN 
LineStart := GetLineSterts( рагатз[1] 2; 
SortText( parems[1] 2; 
newField := SetNewTextC params[1], 
SortOrder ); 
DisposHaendleC HandleC LineStart ) ); 
END; 


NUMERIC: 

BEGIN 

hNums := GetNums( parems[1] ); 

SortNums( hNums ); 

newField :- SetNewNumsC hNums, SortOrder ); 
DisposHandleC HendleC hNums ) ); 


END; 
END; (*** CASE SortOrder OF ххх) 
END; 


peremPtr^.returnValue :- newField; 
END; -— 


END. 29 


алы 
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НурегСйайм 
Script Tips 


on HyperChat 

— HyperEditorial 

When to HyperTalk 

People say that Hypercard is nota real programing language. 
Well what isa program? A program is а series of instructions that 
are processed by a computer to yield a result. We have estab- 
lished that Hypercard is a programing language; now people say 
it is not powerful. What is meant by a powerful programing 
language? Does it mean flexible, or easy to use, or even the fastest 
way to get a result? 

The most flexible language is of course binary because that 
is the native language of the computer. I don’t think anyone 
would call binary a powerful language, it would take too long to 
do anything really useful with it. Hypercard can do some graphic 
manipulations easier than Pascal or C. There are many things that 
can be done in Pascal and C that are too cumbersome in Hypertalk 
or even impossible. In the past I have shown things that have been 
thought to be impossible in Hypertalk. The effort was greater 
than doing them with external commands, but it could be done. 

I believe we are entering an Era of what I call “Russian Doll" 
programing environments. A Russian Doll is a large wooden doll 
which you can open up to find a smaller doll. This process goes 
on many times. The analogy serves programing well. The first 
level is very simple we can, for instance, change command key 
equivalents (like QuickKeys). The next level we can move 
objects around (like buttons in Hypercard); the next level we can 
program the objects with scripts. We then get to the next level 
where we can add external code (C or Pascal). We should also be 
able to change the properties of the level above i.e. Hypercard 
objects. Unfortunately we can’t. We are however at the point 
where we might soon be able to use one script or piece of code in 
different applications. 

Now I come to my definition of a powerful programing 
environment: “A programing environment is powerful if it lets 
you have the flexibility to communicate to other environments 
and utilize routines that have been developed for other purposes.” 
This is why MPW is regarded as a powerful programing tool. The 
developer still has to choose when it is best to use Assembly or 
Pascal or C. If the developer does not have the experience 
necessary in Assembly he can get some other person to do it. A 
similar thing happens in Hypertalk with external commands. 
Wouldn't it be nice to use some of your great scripts and buttons 
you have developed in Hypercard, in MacWrite? 

This month we look at the similarities and differences 
between Hypertalk and Pascal in an article by Paul Merrill. Don 
Koscheka in XCMD Cookbook shows you an example when it 
is best to use Hypertalk and when to use XCMD’S. 
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—ScriptTips 

Last month I brought you AutoHyperEdit the response has 
been great and I am glad to hear that it is finding uses especially 
for the handicapped. Using AutoScriptEdit a person can edit 
scripts quickly one handed. This month I had a request how to 
make buttons 1 or two pixels high. That was easy, you just type 
in the command set the height of btn x to 2 . |wanted an easy way, 
so I added the following italic text to my arrowkey handler in 
AutoHyperEdit. So all you have to do is to shift select the button 
or field, then double click outside an object to get into the action 
mode and hold down the shiftkey and use the arrow keys to make 
the button or field smaller or larger. I could have made it act on 
groups of objects but I wanted to make it modular. I leave it to 
you, to make it work on groups, as an exercise. 


оп arrowkey whichkeg-**AutoHyperEdit**- 
global CWSList 
if the shiftkey is down then 
put item 1 of cwslist into T 
put the width of T into TW 
put the height of T into TH 
if whichkey is "down" then set the height of T to TH- 1 
if whichkey is “up” then set the height of Т to TH + 1 
if whichkey is “left” then set the width of T to TW - 1 
if whichkey is “right” then set the width of T to TW + 1 
end if 
if the mouse is down then 
if whichkey = “left” then 
put the mouseH into L 
repeat with i = 1 to the number of items in CWSList 
put the width of item i of Cwslist into w 
set the left of item i of Cwslist to L 
set the width of item i of Cwslist to w 
end repeat 
end if 


if whichkey = “right” then 
put the mouseH into R 
repeat with i = 1 to the number of items in CWSList 
put the width of item i of Cwslist into w 
set the right of item i of Cwslist to R 
set the width of item i of Cwslist to w 
end repeat 
end if 


if whichkey = “up” then 
put the mouseV into T 
repeat with i = 1 to the number of items in CWSList 
put the height of item i of Cwslist into h 
set the top of item i of Cwslist to T 
set the height of item i of Cwslist to h 
end repeat 
end if 


if whichkey = “down” then 
put the MouseV into B 
repeat with i = 1 to the number of items in CWSList 
put the height of item i of Cwslist into h 
set the bottom of item i of Cwslist to B 
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set the height of item i of Cwslist to h 
end repeat 
end if 
exit arrowkey 
end if 
pass arrowkey 


end arrowkey —**AutoHyperEdit**- 


The second script tip deals with searching in large numbers 
of cards for a checked item. If you have to check for the hilite of 
a button in 2000 cards, it takes a while. If you use a field with a 
check mark and search for the character in the field it is much, 
much faster because it uses Hypercards fast search algorithms. 
Simply lock the field and put this script into it. You could also use 


an ^X" mark. | 


on mouseup 
if me is empty 
then put “Z? into me 
else put empty into me 
end mouseUp 
on HyperChat 


= 
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HyperChat™ 
Comparing HyperTalk to Pascal 


Pascal and HyperTalk: A Comparison 


[Paul F. Merrill is a professor of instructional science and 
computer based education at BYU. He teaches courses in Pascal 
and computer based authoring systems. He has also written a 


book entitled, Computers in Education published by Prentice- 
Hall] 


HyperCard has produced a lot of excitement and discussion 
in the Macintosh community. It has generated a large following 
and no small number of critics. Many proponents have argued 
that HyperCard enables the weekend programmer to create 
sophisticated applications which tap the power of the Macintosh 
user interface without having to digest the formidable tool box 
and “Inside Macintosh.” John Sculley has predicted that it will 
have an impact in the Macintosh world similar to the impact of 
Applesoft Basic in the Apple II world. 

But just how powerful is the HyperCard authoring environ- 
ment and its associated programming language, HyperTalk? 
One way to address that question is to compare HyperTalk with 
some standard language. Therefore, the purpose of this article is 
to compare HyperTalk with the Pascal programming language. 
This comparison will not only reveal the power of HyperTalk, but 
it will also provide a bridge for the Pascal programmer to cross 
over into the new exciting world of HyperCard. 

This article is neither a tutorial in Pascal or HyperTalk. It is 
assumed that the reader has some familiarity with Pascal and has 
at least seen a demonstration of or read a good review article on 
HyperCard. 

The following comparisons will be done by annotated ex- 
amples rather than by complicated syntax diagrams. Since one 
or two examples cannot show the full range of possibilities for a 
given command, page number references are provided to a full 
discussion of the command found in Danny Goodman’s excel- 
lent book, “Тһе Complete HyperCard Handbook.” Pascal ex- 
amples are shown in boldface while HyperTalk examples are 
shown in italics type. Annotations or comments are shown 
within curly brackets. Single spacing will be used to indicate 
commands that go together as a set, while double spacing will be 
used to separate independent examples. 


r r r 
Unlike Pascal, HyperTalk cannot be used to create stand- 
alone programs. Itcan only be used within HyperCard to control 
the activity of HyperCard objects (stacks, backgrounds, cards, 
fields and buttons). HyperTalk is not used to create a “program” 
that is executed from beginning to end. Instead each HyperCard 
object may have associated with it HyperTalk commands called 
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a "script". Each script may contain several Pascal like proce- 
dures called “message handlers." The commands within a 
message handler are executed when an object receives a message 
which matches the handler. HyperCard sends messages to an 
appropriate object whenever certain events occur. For example, 
a button script may have a message handler which will instruct 
HyperCard to go to the next card, using a dissolve visual effect, 
when the mouse is clicked on the button and the “mouseUp” 
message is received. The script associated with that next card 
might contain a message handler which will be executed when 
the card is opened and a corresponding “openCard” message is 
received by the card (see Goodman, pgs. 345-360). An example 
ofa simple Pascal program and two HyperTalk message handlers 
are shown below. The Pascal program calls a procedure “get- 
name" which requests the user's name and then displays “Thank 
you" on the screen. The first HyperTalk message handler 
performs essentially the same functions. It is executed when a 
specific card is opened. The second message handler is executed 
when the mouse is clicked on a button. HyperTalk message 
handlers begin with the word “оп” followed by the name of a 
particular message. They always terminate with the word “end” 
followed by the same message name. In these and subsequent 
examples, you will find that most HyperTalk commands are 
closer to standard English commands than their Pascal counter- 
parts. 


program exemple; 
procedure getnane; 
var 
name: string; 
begin 
writelnC'What is your name?’); 
readinCname); 
writelnC'Thaenk you’) 
end; 
begin 
ge tnane 
end. 


on openCard 
ask “What is your name?” 
put “Thank you” into field ! 
end openCard 


on mouseUp 
visual effect dissolve 
go to next card 


end mouseUp 


тар! ign 
In Pascal, the programmer has to declare what type of values 
will be stored in a variable before it can be used. Local variables 
do not need to be declared in HyperTalk. Global variables are 
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declared іп any handler which uses them. АП HyperTalk уап- 
ables are of type text. Numeric characters are automatically 
converted to numbers before mathematical operations are per- 
formed (Goodman, p. 362). In addition to variables, information 
may be stored and retrieved from other “containers” such as 
fields, the Message Box, and any text selected by the user (p.400). 
The following Pascal examples show the declaration of several 
different types of variables followed by three assignment state- 
ments where mathematical expressions are evaluated and vari- 
ables are given a value. The HyperTalk “put” command also 
evaluates expressions and stores values into variables or other 
containers. Note the additional HyperTalk arithmetic com- 
mands. 


var 
х, y, Sum,counter: integer; 
name: string; 
г: real; 

паве: =Раџ1“; 

әуа:а (xty2*r/2; 


counter:scounter +1; 


put “Paul” into name (p. 415) 
put (xty)*r/2 into sum (p. 415) 
add 1 to counter ф. 441) 


subtract field 1 from sum (р. 442) 
multiply salary by selection (p. 444) 
divide field “total” by num (p. 445) 


Macintosh Pascal provides a text and a drawing window for 
the display of text or graphics. Multiple windows can be 
displayed on the screen using tool box routines in LightSpeed 
Pascal. The present version of HyperCard only allows one 
window or card to be displayed on the screen at a time./In НС 
version 1.2 and later you can selectively hide and show Card and 
Background Picts giving you more graphic control. HyperEd] 
However, HyperCard differentiates between text fields and a 
graphics layer. In the following examples the Pascal “write” 
command is used to display a simple string in the text window, 
while the HyperTalk “put” command is used to display informa- 
tion in a text field. 


write C'Display on the text screen’); 
put "Display in field" into field 2 (p. 415) 


These examples show how values from variables and literal 
strings are combined for display on the text screen or in a field. 
Іп HyperTalk, the double ampersand (& &) adds a space. 


write Cstr1 ,^ literal string ', str2,^ ', str3); 
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put str! & " text “ & str2 && str3 into field “Hello” 


The results of the evaluation of a mathematical expression 
may also be mixed with literal strings. The “:7:2” after the 
expression is used to format the resulting real number in a seven 
column field with two digits after the decimal. HyperTalk re- 
quires an additional command, “set numberFormat," in order to 
format the real number. 


write C'Your salary is *, rate*hours:7:2); 


set numberFormat to "8.00" (р. 489) 
put "Your salary is * & rate*hours into field “salary” 


The Pascal “writeln” command is exactly the same as the 
“write” command, shown above, except it places a "carriage 
return" character at the end of the line. To do the same thing in 
HyperTalk, the “return” character must be given explicitly as 
shown in the following example. However, in HyperTalk it is 
generally not necessary to specify the “return” character since the 
text will automatically be “word wrapped" within the dimensions 
of the field. This capability makes it possible to use one 
HyperTalk “рш” command where several Pascal “writeln” 
commands would be necessary. 


writeln C'Text followed by return’); 


put “Text” & return after field "display" (p.415) 


Macintosh Pascal provides three commands, “drawChar,” 
"drawString, “ and “writeDraw” for displaying text on the 
drawing screen. Each of these must be preceded by a “moveto” 
command which specifies the coordinates of where the text is to 
be displayed. In HyperCard, the “type” command is used to place 
text in the graphics layer of a card. This command must be 
preceded by other commands which select the text tool and 
specify the location of where the text is to be placed. For many 
applications, text may be placed in fields and on the graphics 
layer of a card using the MacPaint like tools built into HyperCard 
rather than using HyperTalk commands. Text placed in fields 
may be edited by the user, while painted text in a graphics layer 
cannot be edited. However, painted text may be erased using the 
erasure tool or moved using the lasso tool. 


moveto (40,100); 
writeDraw C'Display in drawing window’); 


choose text tool (р. 429) 
click at 40, 100 (p. 430) 


type "This is painted text” (р. 433) 


In Pascal, user input from the keyboard can be obtained by 
using the “read” or “readln” commands. These are generally 
preceded by a prompt displayed by the "write" or "writeln" 
commands. HyperTalk provides several techniques for obtain- 
ing keyboard input from the user. The “ask” command displays 
a dialog box with the first string argument as a prompt and the 
second string as the default selected response. Тһе user's 
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response is stored in the HyperTalk system variable called “it.” 
The "answer" command displays a dialog box with the first 
string argument as a prompt and two or three pushbuttons each 
labeled by the succeeding strings. When the user clicks a button, 
the button label is placed in the variable “it.” Unfortunately, the 
location of these dialog boxes cannot be controlled by Hyper- 
Talk. The "put" command may be used to place a copy of 
whatever the user types into an editable field into a specified 
variable, while the "get" command places the contents of a field 
in the system variable "it." 


write (‘Please enter your паве ”); 
readin(name); 


ask "Please enter your name" with "Paul" (p. 465) 


answer "Are you happy” with “yes” or “no” or 
“maybe ^ (о. 463) 


put field 1 into address (р. 415) 


get field name (о. 419) 


rator f 
The following math and boolean operators are the same in 
both languages. However, HyperTalk includes the additional 
operators: “is” and “ 1$ not” (р. 563-576). 


+ - * / div mod = <> < <= >= andor not 


The Pascal “random” function returns а random number 
between -32767 and +32767, while “Ше random" function in 
HyperTalk returns a random number between 1 and a specified 
value. 


x:=randon; 


put the random of upper into x (о. 545) 


The following math functions are the same in both lan- 
guages. HyperTalk also provides several additional functions 
such as "annuity" and "average" (p. 546-551). 


round, (гипс, abs In, sqrt, cos, sin, exp 


Sequence contro! structures 

Both Pascal and HyperTalk provide powerful if-then-else 
control structures with very similar syntax. The following 
examples display different messages on the text screen (Pascal) 
or in a field (HyperTalk) and increment different variables (count 
or ave) depending on the values of the variables “status” and 
"gpa." There is no HyperTalk equivalent of the Pascal “сазе” 
statement other than nested "if-then-else" commands (p. 589). 


if (status = , undergrad^) and Сора > 3.7) then 
writeinC'Deans list’) 
else if ора < 2.8 then 
begin 
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writelnC'Probation^); 
count : = count + 1 
end 
else 
begin 
writeln( Average’); 
ave : = ave + 1 
end; 
if stat = “undergrad” and gpa > 3.7 then (р. 584) 
put “Deans List” into field 1 (о. 415) 
else if gpa ‹ 2.8 then (о. 587) 
put “Probation” into field ! (p. 415) 
add 1 to count (о. 441) 
else (p. 
587) 
put “Average” into field 1 (p. 415) 
put ave * 1 into ave (p. 415) 
end if 
(p. 587) 


Both Pascal and HyperTalk provide several very powerful 
repetitive control structures with similar syntax. However, 
HyperTalk provides an additional structure not found in Pascal 
and also adds several abnormal exit features not shown in the 
examples: "next repeat,” “exit repeat," “exit if," and “exit 
«handler name» (p. 594). The following repeat loops will 
continue asking for a number from the user and display the value 
of the number multiplied by 10 until the user enters the number 
“0.” 


repeat 
WriteinC'Enter а number ^); 
readin Cit); 


writelnCitt18); 

until it = 9; 

repeat until it = 0 (p. 591) 
ask "Enter a number” (р. 465) 


put it *19 & return after field 1 
end repeat 


(p. 415) 


The following "while" loops will continue asking the user to 
enter anumber and display the dividend produced by dividing the 
number into 50 until the user enters the number “0.” 


writeln C’Enter a number ^); 
readin Cit); 
while it do 
begin 
writeln (59/11); 
writelnC'Enter a number’); 
readincit); 
end; 


ask “Enter а number” (о. 465) 

repeat while it is not 8 (p. 592) 
put 50/it & return after field *answer^(p. 415) 
ask "Enter а number” (p. 465) 


end repeat 


These “for do" loops will display the product of the integers 
5 through 20 each multiplied by 5. The Pascal “for do" may also 
use “20 downto 5" while the HyperTalk "repeat with" may use 


611 


“20 down to 5." 


for і: = 5 to 28 do 
writelnCi*5); 


repeat with i = 5 to 20 (p. 5932.) 
put i*5 & return after field “product” 
end repeat 


This HyperTalk loop will repeat 20 times. Each time it will 
place the string "I love you" into field 3 and sound a beep. 


(No Pascal equivalent) 


repeat 20 times (p. 590) 


put “I love you * after field 3 (p. 415) 
beep 1 (p. 469) 
end repeat 


QuickDraw Graphics 

Pascaland HyperTalk both provide commands for accessing 
the Macintosh QuickDraw Graphics routines. In most Hyper- 
Card stacks, the use of HyperTalk graphics commands within 
scripts will not be necessary since the drawing of graphics can be 
done with the MacPaint like tools included within HyperCard. In 
fact, HyperTalk graphics commands, used in scripts, actually 
provide access to the same tools found in the HyperCard tools 
menu. Therefore, the equivalent of most Pascal graphics com- 
mands are implemented in HyperTalk by selecting a particular 
graphics tool using the “сһоове” command and then simulating 
the dragging of the mouse across the screen using the “drag” 
command. Note that the arguments for the "drag" command are 
in a different order than those of the Pascal “frameRect” com- 
mand. Ovals and rounded rectangles can also be drawn with 
HyperTalk by first selecting the corresponding tool. Three or 
four HyperTalk commands arerequired to implement the equiva- 
lent of some Pascal graphics commands such as “paintCircle” 
and “invertRect.” 


drawLine (x1,y1,x2,y2); 


choose line tool (р. 429) 
drag from х1,у1 to x2,g2 (p. 431) 


frameRect (top, left, bottom, right); 


choose rectangle too! (р. 429) 
drag from left, top,right, bottom 


(о. 431) 
paintRect (г); 
set filled to true (p. 495) 


choose rectangle tool (р. 429) 
drag from х1,у1 to х2,у2 (p. 431) 


paintCircle Cx1,y1,r2; 

set filled to true (p. 495) 

set centered to true (p. 495) 
choose oval tool (р. 429) 
drag from х1,у1 to x1,y2 (p. 431) 
invertRect(r); 


choose select tool (p. 429) 
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drag from х1,у1 to x2,g2 (p. 431) 
doMenu “invert” (p. 421 & 247) 


егазеКесі (г); 


choose select tool (p. 429) 
drag from x1,y1 to x2,g2 (p. 431) 


doMenu "clear picture” (p. 421) 
penSize (4,4); 
set lineSize to 4 (р. 497) 


penPat (grau); 
set pattern to 19 (р. 498) 
penMode СраїХог); 


(No Hypertalk equivalent.) 


Pascal provides several commands for controlling the prop- 
erties of text displayed on the drawing screen by subsequent 
writeDraw commands. Іп HyperTalk, many properties of 


painted text, buttons, and fields may be changed using the "set" 
command. 


textFont (3); 

set textFont to Chicago (painted text (p. 4992) 
textFace CI[bold,underline1); 

set textStyle of button ok to bold, underline (p. 499) 
textSizeC 18); 

set textSize of field 2 to 18 (p. 499) 

textMode CsrcXor); 


(No Hyper Talk equivalent .) 


Mouse Control 

The Macintosh tool-box ROM contains several routines, 
which can be accessed by Pascal commands, for tracking mouse 
events such as clicking the mouse button and moving the mouse. 
The "button" function returns a value of “true” if the mouse 
button is pressed down at the time the function is called; other- 
wise it returns "false." The “getMouse” procedure returns the 
coordinates of the position of the mouse pointer at the time the 
procedure is called. Although there are directly equivalent 
commands in HyperTalk, as shown below, mouse events are 
mainly tracked by message handlers which trap for mouse related 
messages: “mouseDown,” “mouseUp,” *mouseEnter," “mouse- 
Leave,” “mouseWithin,” and *mouseStillDown" (р. 383-386). 
A “mouseUp” message handler is generally used to respond to 
normal mouse clicks within buttons, fields and card. In the 
examples below, “the mouseLoc” function returns the current 
position of the mouse pointer, while “the clickLoc” function 
returns the position of the mouse at the last click. 


tf :=button; 


put theMouseClick into tf (о. 534) 
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getmouse(x,y); 


put the mouseLoc into xy (p. 529) 


put the clickloc into ху (p. 535) 


String procedures and functions 
Macintosh Pascal provides several powerful commands for 
manipulating strings. HyperTalk provides even greater power by 
making it possible to manipulate characters, words, lines and 
items within any container. 


it:slength Cstr); 
get the length of word 3 of field “input” (p. 537) 
it:=concat(stri,’ literal *, str2,’ ”, str3); 


put stri & * literal string * & str2 && str3 into it 


(88 adds а 
space (p. 415)) 


it:=copyCsource, firstchar, nusofchar); 


get char 3 to 8 of line 3 of field "source" (р. 419) 


delete Csource, firstchar, numofchar); 
delete item З to 8 of field 3(p. 420) 


insert(source, dest, 5); 


put selection before fifth word of field 2 (р. 415) 


The Pascal command “ров” is used to find the location of a 
pattern in a source string. It returns a number indicating the 
location of the first occurrence of the pattern. Zero is returned if 
the pattern is not found. The HyperTalk “offset” command 
performs exactly the same function. Two other HyperTalk 
commands, “contains” and “і in" return the value “true” if the 
pattern is found in the source. 


if pos (pattern, source) €» 6 then 
writeln (‘Correct’); 


if offset (pattern, source) О 2 then (p. 538) 
put “correct” into field “feedback” (р. 415) 


if source contains pattern then (p. 573) 
put “correct” into field "feedback" (p. 415) 


if pattern is in source then (p. 573) 
put “correct” into field “feedback” (р. 415) 


Sound Commands 

A single voice note can be played by using the “note” 
command in Pascal. This command requires three integer 
arguments which specify the pitch, loudness and duration of one 
note. The HyperTalk "play" command is more versatile with 
arguments to indicate the instrument or waveform, the overall 
tempo, and a series of notes specified by normal musical sym- 
bols. For example, the notation “с#4е.” would indicate a dotted- 
eighth c-sharp note in the 4th octave (middle octave). The “play” 
command can also be used to produce various self contained 
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digitized sound effects. Such sounds may be recorded using a 
digitizer and converted to a Mac resource file. 


note (448, 75, 48) 
play “harpsichord” tempo 380 "ЪЗ c#4 d e Г# д a83” 


play "breaking glass" (р. 470) 


User defined types: arrays and records 

On first glance, HyperTalk doesn't seem to support user 
defined types such as arrays and records. However, a card is 
analogous to a record which can contain many different named 
fields. Each field can contain up to 32 K. Field data can be 
accessed by line, item, word or character. Lines are separated by 
carriage retums, items by commas, and words by spaces. Data 
fields may be hidden from view if desired. The following 
HyperTalk script will compute the average of a set of numbers 
found in a field labeled "scores" for each card in a stack. Each 
number is separated by a space and considered to be a word. 


Type scorearray - array [1..25] of integer; 
student - record of 
name: string[35]; 
data: scorearray; 


end; 
class - array [1..100] of student; 


repeat with n 2 1 to number of cards . 593 
5% іо сага п f (P 107, 
put 0 into sum ір, 41 
put the number of words in field "scores" into 


num (p. 415) 
repeat with i 2 1 to num (p. 25 
add word i of field "scores" to sum Б 441 
end repeat 
put sum/num into field average {p. 415} 
end repeat 


Pascal has three different commands to open а file. “Ке- 
write” is used to open anew sequential file, “reset” is used to open 
a sequential file that has been previously created, and “open” is 
used to open a new or previously created random access file. 
These commands can be used to open simple text files or 
structured or typed files. In contrast, HyperTalk only deals with 
simple text files and only has one open command: 


rewrite Се, filename’); 


open file “filename” 
reset (f,’filenane’); 


(о. 475) 


open Се, ’filenane’); 


In HyperTalk, if several fields are written to a file they 
should be separated by writing a “tab” character to the disk (write 
tab to file filename"). Records or cards should be separated by 
writing a Return character to the file (write return to file “file- 
name”), 


write Cf, classiil. data); 


write field “data” of card i to file “filename” (p. 478) 
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Тһе HyperTalk “read” command just reads characters from 
the file until it finds a delimiter such as “tab” or “return.” The text 
is placed in the variable “it”. The delimiter characters should be 
removed before placing the text in a field. 


read Cf, class[i] data); 


read from file “filename” until tab (p. 476) 


close (f); 


close file "filename" (р. 475) 
User defined functions and subroutines or 
r | 

The specification and calling of user defined functions in 
Pascal and HyperTalk is almost identical. The following ex- 
ample functions require two integer parameters and return the 
value of the first parameter raised to the power specified by the 
second parameter. 


function power Cnum, exp: integer): integer; 
var 1, апзи: integer; 
begin 
апзи:=1; 
for 1:=1 to exp do 
ansu: =апзи пив; 
power : =апзи; 


end; 
function power num,exp р 561) 
put 1 into answ p. 415) 


repeat with i = 1 to exp (р. 593) 
multiply answ by num (о. 444) 

end repeat 

return answ (p. 561) 


end power 


The following commands show how the functions defined 
above might be called. 


writeinCpowerC5,3)22; 
put power (5,3) into field 1 (p. 561) 


Similar to Pascal, HyperTalk provides for user defined 
subroutines, procedures or handlers with value parameters. 
HyperTalk also provides for both local and global variables. 
Local variables do not have to be declared in HyperTalk. Global 
variables must be declared in all subroutines or handlers which 
access them. In contrast with Pascal, HyperTalk handlers must 
return values through global variables since there is no provision 
for variable parameters. The following example procedure and 
handler compute the power of a number similar to the functions 
shown above. 


procedure power (num, exp: integer; ver answ: 
integer); 
var i:integer; 
begin 
answ:#1; 
for 1:21 to exp do 
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answ:zansw*num; 


end; 

on power num,exp 
global answ (p. 457) 
put 1 into answ (0. 415) 


repeat with i = 1 to exp (p. 593) 
multiply answ by num (p. 444) 
end repeat 


end power 


The procedure or handler defined above would be called 
using the following commands. In the HyperTalk example, the 
global variable “answ” must be declared in any handler which 
calls the subroutine “power.” 


power (5,3,result); 
writeln (result); 


global answ 
power 5,3 


put answ into field “output” 


Summary and Conclusions 

Based on the comparisons presented above between Pascal 
and HyperTalk, it should be clear that HyperTalk is indeed a 
powerful language with many similarities to Pascal. It provides 
sophisticated sequence control structures, user defined subrou- 
tines and functions with parameter passing, a variety of data 
structures, powerful math operations and functions, string ma- 
nipulation functions, text display, graphics and sound com- 
mands, and disk file input/output routines. Not shown in the 
comparison is HyperTalk’s ability to call subroutines and func- 
tions recursively. These similarities should make it possible for 
Pascal programmers to become proficient in HyperTalk without 
undo effort. 

In addition to the similarities with Pascal, HyperTalk also 
has some object oriented programming features similar to lan- 
guages such as SmallTalk and some list processing features 
similar to languages such as Logo and Lisp. HyperTalk contains 
several other commands that have no Pascal equivalent, and 
therefore are not included in this comparison. Two of these 
which deserve special mention are the “edit script” and “do” 
commands. “Edit script” can be used to create and modify scripts 
from within a HyperTalk script, while the “do” command can be 
used to execute commands stored in a container such as a variable 
or field. 

The HyperCard environment also provides a text editor and 
MacPaint type graphics tools. These tools, along with the 
capability to import text and graphics, makes it possible to easily 
create screen displays without having to rely on complicated 
programming commands. 

HyperCard with HyperTalk does indeed provide a powerful 
and exciting programming environment. There are limitations 
such as screen size, lack of color, no commands for creating 
menus and dialog boxes, and the speed limitations of an inter- 
preted language. However, many of these limitations may be 
rectified in future versions of HyperCard, or through the use of 


external commands written in other languages. 
Ser 
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HyperChat™ 
XCMD Corner 


Importing Text into Hypercard 


A new controversy seems to be emerging in the Hypercard 
community. Some Hypercard pundits are discouraging the use 
of XCMDs and XFCNs in stack design.. Their most convincing 
argument is that those of us who jump into writing XCMDs 
aren’t giving ourselves an opportunity to see if HyperTalk can 
perform the task, perhaps equally as well as an XCMD. 


I frequently consider writing an XCMD solution to a 
programming problem without first considering whether Hyper- 
talk can do the same job for me. Recently, I needed to import 
Microsoft WORD files into Hypercard. What a wonderful 
opportunity to write an XCMD! 


When I sat down to write the script to invoke the XCMD, I 
realized that I could write the entire WORD import routine in 
HyperTalk. Ed Wischmeyer of Apple Computer Inc. pointed out 
that although fields in HyperTalk prefer to see straight ASCII 
text, there is no such restriction on the contents of containers. 
Hypercard also allows you to open and read any file type you 
want; you aren’t restricted to reading text files. Of course, you 
need to figure out how to translate what’s in that container into 
a format that can be presented in a field. 


The hard part of importing text from a Word file is not 
reading the data into hypercard but rather figuring how Word 
Stores its text. By committing the import code to a simple 
Hypertalk script, I could concentrate my efforts at decoding 
Word’s file format. 


To simplify my search through the file format, I made the 
assumption that I could ignore any formatting information such 
as rulers, font and style changes. I was after was the text portion 
of the file only. This turns out to be a valid assumption since I 
wanted to import the file into a Hypercard field as text. 


Finding the text was а snap with John Mitchell's “FEDIT+”. 
I created a Word file using WORD and then examined it in 
FEDIT-+. I noticed that the text always started at location 256 in 
the file. Since the size of the file was larger than the size of the 
text plus this 256 byte header, I needed to determine where the 
end of text occurred (assuming that the formatting and ruler 
information follows the text in the file). Since I knew how long 
the text was, I again used FEDIT+ to search the 256 header 
portion of the file. This timeI was looking for any portion of the 
header that contained a count of the number of bytes in the text. 
Since I knew that my file contained exactly 100 characters 
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(bytes), all I had to do was find this number somewhere in the 
header portion of the file. I found something close to what I was 
looking for at offset 16 in the file. This location corresponded to 
the number of characters in the text portion of the file plus 256 
which was the length of the header. 


The creators of Microsoft Word may be reading this and 
wondering why I’m assuming that the text size is a 16-bit entity 
rather than a 32 bit number. I'm not. Since Hypercard text fields 
are currently limited to 32K bytes, and since I knew none of my 
word files were longer than this, I' m only interested in the low- 
order word of the text length. 


Reading the text portion of a Microsoft Word file into a 
hypercard container requires the following steps: (1) Position the 
mark at byte 16 of the file. Read the byte at this position and 
multiply it by 256 making it the high-order half of the file length. 
Read the next byte and add it to the hight-order half of the length. 
Move 238 more bytes into the file (1642-238 = 256). This is the 
start of the text portion of the file. Read the number of bytes 
calculated minus 256. The IT container gets the imported text. 


The Hypertalk script in listing 1 performs the above steps for 
importing up to 16K bytes of text from a Word file. I use Steve 
Maller’s “FileName” XCMD to display WORD files only in the 
GetFile dialog and to get the full pathname of the file from the 
user. This script reads in the text without any looping so an 
XCMD may not speed things up enough to be warranted. 


on mouseup 
put filenameC“WDBN’ into filename 
if filename is not empty then 
open file filename — filename is the full pathname of a WORD 
file 
read from file filename for 16 - move file mark to the text 
length word 
read from file filename for 1 - read the upper half of the 
length 
put chartonumC it ) * 256 into filesize - shift up by 8 bits 
read from file filename for 1 - get the lower half of the 
length 
edd chartonumC it ) mod 256 to filesize 
read from file filename for 238- move to start of text in the 
file 
read from file filename for filesize-256 - read in the text 
close file filename - IT now contains the imported data. 
end if 


end mouseup 


Listing 1. Script to Import Text from a Microsoft 
Word File 


Not all file formats can be imported quite so simply. 
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Macwrite usesa packed text format, storing one or two characters 
per byte using a simple compression scheme. 


Because the text is compressed, we can't just read the file 
into a container and return the result to Hypercard. We must first 
decompress the file a byte at a time. Such a process suggests 
looping and loops, as we know, are not particularly fast in 
HyperTalk. Although the decompression can be performed in a 
hypertalk script, we can write an xcmd that performs the decom- 
pression faster. 


The key to reading іп a MacWrite file is understanding that 
Macwrite stores its data by paragraph. Whereas Word files are 
clearly divided between the text and formatting information, 
Macwrite stores formatting information for each paragraph at the 
end of the text for that paragraph. Hypercard doesn't do format- 
ted text; we want to ignore the formatting information at the end 
of each paragraph. Our algorithm then becomes a loop that reads 
in а paragraph ata time, decompresses the text for that paragraph 
ignoring the formatting information. This process is repeated for 
each paragraph in the file. 


One small “gotcha” to this approach stems from the fact that 
Rulers and pictures are also considered paragraphs. When we 
encounter either of these objects, we just move on to the next 
paragraph. 


Listing 2 depicts the code for this XFCN. I chose "C" 
because pointer arithmetic is easier to perform in "C" and 
because last month'sexample was written in Pascal. Imadeevery 


attempt to keep the “С” isomorphic to a Pascal program so that 
you can easily convert the code to Pascal. 


Finding the paragraph information in the file requires a little 
arithmetic. Bytes 2-3 in the file tell us how many paragraphs the 
main document contains (Mac Write makes a distinction between 
the main document, the header document and the footer docu- 
ment. For our purposes, we only want to read in the main body 
of text) If bytes 2-3 contain a 5 then there are 5 paragraphs in the 
main document. 


For each paragraph, MacWrite stores an information array. 
We start reading the information arrays at the file position 
pointed to in file offset $108. An information array is an array of 
16-byte elements that tell us something about each paragraph. 
The first two bytes in the information array tell us whether the 
paragraph contains text, a ruler or a picture. If this value is 
positive the paragraph contains text, if this value is O or negative 
the paragraph isaruler ora picture respectively and wecan ignore 
it. 


Offset 8 in the information array contains a status byte that 
provides some information about the text. If bit 15 set, the text 
in this paragraph is compressed. Bytes 9-11 tell us the absolute 
file offset for the start of the data in the paragraph and bytes 12- 
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13 contain the length of the data (paragraph addressing is 24 bits 
and each paragraph contains up to 64K of characters or data). The 
trick is to read in the number of characters indicated in the 
information array, determine if the paragraph contains text and, 
if so, decompress the text if it’s compressed. 


Once we read in the paragraph, we get some more informa- 
tion. The first two bytes of the paragraph tell us how many 
characters of text will appear in the decompressed paragraph. 
Following the text on an even word boundary is the formatting 
information for the paragraph which we ignore in this example. 


MacWrite’s text compression is based on a letter frequency 
scheme stored as STR resource #700 in MacWrite’s resource 
fork. For English, this string contains “ etnroaisdlhcfp”. 
Macwrite maps these characters onto the array [$0..$F]. The 
space character ($20) has a value of 0, letter “e” has a value of 1, 
“t” a value of 2 and so on. Since any number less than $F can fit 
into a nibble, the word “eels” can be represented as “$11A8” 
rather than the byte-wide representation of $65656C73. In this 
example, we realize a 50% space saving (the best case for this 
algorithm). 


This compression scheme only works for lower-case letters 
since 4 bits is not enough information to code for word frequency 
and case for the 14 most popular letters. This scheme also doesn't 
compress non-alphabetic characters such as numerals and punc- 
tuation marks. In these cases, the 16th array element, $F, is used 
as a flag to tell indicate that the next 2 nibbles represent one 
character. "Then" would be coded as $F55906. Note that the 
letter “Т” crosses byte boundaries, the top nibble is in byte 0 and 
the lower nibble is in byte 1. This is of no consequence to the 
algorithm. 


Armed with this information, you should have little trouble 
understanding the XFCN. In fact, I hope you find it useful and 
informative! (Next month: printing from XCMDs). 


/ FX XXXXXXXXXOOOOOCECEOIOOOEEXOEN 
file: MWRead.c x 


an XFCN that imports text 
directly from a MacWrite file 
whose full pathname is passed 
as an input parameter. 


* »* »* и и и 


x 


To Build this file: 
C -q2 -g MWRead.c 


link -sn Main=MWRead д 

-sn STDIO=MWRead д 

-sn INTENV=MWRead д 

-rt ХЕСМ-301 д 

-m MWREAD MWRead.c.o д 

* (CLibreries)^CInterface.o д 
-0 "your stack name” 


3 5 39 t »* иии м и М 


x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x x 
х 


* 


By: Donald Koscheka 
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* Date: 2-July- 1988 

* € 1988, Donald Koscheka 
ж А11 Rights Reserved 
x 
x 


% и и м 


eterna x 
\ХЖЖЖЖЖЖЖЖЖЖ ЖЕ ЖЕ ЖЕ ЖЖЖЖЖХ / 


8 include «(Types .h? 

* include «0SUtils.h» 

® include «Memory .ћ› 
8include «Files.h» 

"S include «Resources.h? 
8include *HyperXCmd . h^ 


#def ine INFOPOS 0х00000 108 
def ine PPOS 0х00000002 
"def ine COMP 0х0008 


=: | 

/* Define the structure of an */ 

/* information array element */ 
*/ 

/* pHite is positive if this */ 

/* info array points to text, */ 

/* ignored otherwise. х/ 


/* fPos is the absolute file */ 
/* position of the start of  */ 
/* the paragraph in the file */ 


/* fLen is the total length of x/ 
/* the file including formats */ 
——M х/ 


typedef struct infoArr ( 
short pHite;/* parag hite */ 
short pixels;/* ignore this — */ 
long pHand;/* ignore this */ 
char status;/* chk comprsn  */ 
cher hiMark;/* msw of mark  */ 
short loMark;/* ]sw of mark  */ 
short fLen; /* рагад. Теп х/ 
short fmat; /* ignore this %/ 

)infoArr; 


Ce чу 
short ReadF i le(2; 
Handle DeCompressC); 


pascal void MWRead( paramPtr ) 
XCmdBlockPtr paramPtr ; 

ЫЫ 552222222222 222. 

ж In:ParamPtr: 

* pointer to XCMD param 

block. рагатѕ [9] is the 

name of the macwrite file 

to open. 


Out :ParamPtr->returnValue 
empty if data could not 
be read, text portion 


of a Macwrite document. 
ЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ / 


( 


short 


мии к и MH и и и 


ref, /* file reference 
err, /* io error */ 
vRef, /* vol reference 
pont, /* * paragraphs 
tSiz, /* text length 
loop; /* loop counter 
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long 
fSiz, /* data size 47 
iSiz, /* out data size */ 
iMark,/* iarr file роз  */ 
fPos; /* para. offset  */ 
Handle 
ImportText, 
decomp, /* decompressed* / 
temp; 
infoArr 
info; 
char | 
*fName, 
vName[32]; 


ImportText = nil; 


ifC paramPtr->params(8) != nil )( 


HLock¢ 


GetVol 
f Name 
err = 


peremPtr-?perems[2] ); 


( vName, &vRef ); 
= *(paremPtr-?params[0]1); 
FSOpen( fNeme, vRef, &ref ); 


HUnlockC рагамР{г-›рагатз [0] ); 


ifC err == noErr ){ 


ImportText = NewHandle( 0 ); 


/* get paragraph count x/ 
fSiz = sizeofC short ); 
err-ReadF i leCref , fSiz, &pcnt, Clong)PP0S); 


/* get infodArray position х/ 
fSiz = sizeofC long 2; 
err-ReadF i leCref ,fSiz, &iMark, (long) INFOPOS); 


/* read in the paragraphs х/ 
forC loop = Ø; loop < pent; 100р++)( 
fSiz = sizeof( infoArr ); 
err-ReadF i leCref ,fSiz,&info, iMark); 


ifC info.pHite > 0 )( 
/* paragraph is text x/ 


/* calc text position — */ 
fPoszCinfo.hiMark««0x10)* info. loMark; 


/* get the cher count */ 
fSiz - sizeofC short ); 
err = ReadFileCref,fSiz,&tSiz, fPos); 


/* read in the text x/ 

temp = NewHandleCClong)tSiz2; 

HLockC temp ); 

fPos += 2; 

fSiz = Clong)tSiz; 

err = ReadFileCref,fSiz,*temp, fPos); 


if€ info.stetus k COMP ){ 
/% paragraph is compressed х/ 
HLockC temp ); 


decomp = DeCompress( *temp, tSiz ); 


HUnlockC temp ); 
DisposHandleC temp ); 


temp = decomp; 
tSiz = (short )GetHandleSize( decomp ); 
)/* if( info.status & COMP ) */ 


iSiz = GetHaendleSizeC ImportText ); 


fSiz = Clong)tSiz; 
SetHendleSizeC ImportText, iSiz*fSiz 2; 
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BlockMove(*temp, (*ImportText)+iSiz, fSiz); 
HUnlockC temp ); 
DisposHaendleC temp 2; 
)/* if€ info.pHite › Ø ) */ 
iMark = iMark + sizeof( infoArr 2; 
)/* FOR paragreph count */ 


iSiz = GetHandleSizeC ImportText 2; 
SetHendleSizeC ImportText, iSiz*1 ); 
*((*ImportText)+íSiz) = 40” 


FSClose( ref 2; 
FlushVolC nil, vRef ); 
)/* if file opened ok x/ 


a E = [mportText; 


) 

short ReadF i leC ioRef ,siz, buf, from) 
short ioRef ; 

long siz; 

char *buf ; 

long from; 


[ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ЖЖ ЖЖ 


ж read cnt bytes from the file specified by parms and put 
the data into the buffer pointed to by buf 


ioRef z file reference number 

siz = number of bytes to read 

buf = where to read in to 

from z where in file to read from 


є o HM HM и жм 


ж from is the file mark relative to the start of the file from 


* which the read is to start. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ / 


( 
short err; 
err = SetFPosC ioRef, fsFromStart, from 2; 
ifC err == noErr ) 
err = FSRead( ioRef, &siz, buf 2; 
return( err); 
) 
Handle DeCompress( inp, expcnt ) 


cher *inp; 
short expcnt; 
[ FXXXXOOOOOOOEOE EXEEXEOE 
ж Decompress the input handle’s data CinH) and put the result 
х in the output Handle (outH). outH is sized properly and 
* we use the following scheme: 


*0123456789ABCDEF 

ж etnroaisdihcfp! 

x 

* where _ = SPACE 

х ! = not compressed 

x 

* Consult MacWrite resource str 8700 for the decompression 
x 


string in your file (different for other languages). 
cycle through until the decompressed string count 


x matches the expected count 
ЖЖЖЖЖЖ ЖЖ ЖК AKA ЖЕ ЖЖЖХ / 


% 


( 
short chcnt; 
register char *op; 
register char hiNib; 
register сһаг loNib; 
char dc[ 16); 
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Handle outH; 


outH = NewHandleC ClongJexpcnt 2; 


dc[0] = 0х020; 
dc[1] = ʻe’; 
dc(2] = 4” 
dc[3] = ‘п’; 
dc[4] = ‘г’ 
dc[5] = ‘0’; 
dc[6] = ʻa’; 
dc[7] = ‘i’ 
dc[8] = 's'; 
dc[9] = 'd'; 
бсі101- ‘1’; 
dc[11] = ‘h’ 
05112] = с” 
dc[13] = ‘f’; 
dc[14] = 'p'; 
HLockC outH 2; 
op = *outH; 
chent = 0; 


whileC chent < ехрспі )( 
hiNib = loNib = *1пр++; 
hiNib = hiNib >> 0x04; 
hiNib &= £x090F ; 
loNib &= 0х00ЙЕ; 


ifC hiNib < OxOF 2( 


жор = 
chcnt++ 


dc[hiNib]; 


2 


ifC loNib < OxOF )( 
*0р++ = dc[loNib]; 
chcnt++; 


else( /* next BYTE is a char */ 
*op++ = *inpt++; 
chcntt+; 


else ( 
/* next 


2 nibbles represent %/ 


/* a complete char which*/ 
/* is on odd-nibble bounds */ 


*op = loNib << 8x4; 
hiNib = *inp**; 

loNib = hiNib & 0х000Ғ; 
hiNib = hiNib >» 8x04; 
hiNib &= OxOF; 

жор = ор | hiNib; 

ор++; 

chent**; 


if€ loNib < OxOF ) 
*ор++ = dc[loNib]; 


else 


*optt = *inptt; 


) 


) 
HUnlock(C outH 2; 
returnC outH ); 


Rinclude «XOndGlue. inc.c? 


chent**; 


Listing 2. XFCN to Import trxt from a MacWrite 


Document 


Se 


«Ажы 
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HyperChat™ 
Happy Birthday 


on HyperChat 
Happy Birthday HyperCard 


MacWorld once again has brought us HyperCard-this time 
in it’s first birthday shoes. There were forums dedicated to 
HyperCard and a first birthday extravaganza party which in- 
cluded a giant cake and a HyperCard time capsule. 

The exciting thing at the show was a trend to expand the uses 
HyperCard. 

Apple 

Bill has done some more magic by creating Hyperscan, 
which is a stack that controls the new Apple scanner. Apple has 
also released through APDA a serial toolkit that allows you to 
access the serial ports through а series of XCMD’s. Also released 
is a Laserdisc driver Interactive video toolkit that allows you to 
build videodisc stacks, and a HyperAppletalk driver that allows 
you to make networked HyperCard Stacks (this was written by 
Don Koscheka). Needless to say we will have some great articles 
on this in the future. 

Versacad 

А very novel way of using HyperCard was implemented by 
Versacad. They open Versacad files with HyperCard and get a 
list of objects in a drawing (HyperCard can open any file, and 
information can be written or retrieved by knowing the offset of 
items), then they use HyperCard to do a cost analysis of the 
project. For example, you put in the cost of each part of a motor, 
and HyperCard does the calculations. 

Bright Star 

Bright Star technology have released their HyperCard Face 
driver (see May issue) called HyperAnimator. This is the type of 
technology that will lead us to the Knowledge navigator. I will be 
showing you how to use this technology in innovative ways in a 
later issue. (See Figure 1). 

ACM 

I was at SIGGRAPH just before MacWorld, and it was really 
interesting to see the Mac being accepted warmly by the graphics 
crowd. The Association of Computer Machinery (ACM) has 
released a great Database of HyperText articles using Hyper- 
Card, a valuble resource. (See Figure 2). 

Stack Starter 

This is a stack which has the best collection of innovative 
buttons and controls that I have seen, including incredible ani- 
mated icons with sound effects. This stack was written by 
Robertson Smith and is Shareware available from Cumputer- 
ware and ВВ”. (See Figure 3). 

Amanda Stories 

Amanda Goodenough has brought out another story Called 
“Үош faithful Camel goes to the North Pole." Amanda is a story 
herself. She is a person that was unknown in the computer 
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industry a year ago and now is very involved in the industry. She 
created “Inigo get's out”, and the response from children was so 
great, it made us adults look at what she was doing. She was a 
speaker at Mac World and is praised for her stack simplicity. I will 
demonstarate some of the concepts of design that Amanda is 
trying toconvey in an article ina later issue. I think we should take 
an example from Amanda that Simplicity and content are the 
keys to good stack creation. 
Great Book 

Gary Bond's XCMD’s for HyperCard is a must if you аге 
witing XCMD's; it is a good beginners guide and a great 
reference book. 


Figure 1. HyperAnimator From Bright Star 
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Print Manager Access 

Printing may not come to mind as an area where writing an 
XCMD might be useful since HyperCard prints card reports. 
Perhaps you don’t like the reports that HyperCard prints out, or 
you want to set your own margins or draw borders around each 
field that’s printed out. XCMDs provide access to the ToolBox 
Print Manager, empowering you with the capability of perform- 
ing custom printing in HyperCard. The Print Manager, then, 
becomes a good candidate for XCMD exploration. 


Reporter.P 

This month's XCMD, Reporter.P ( see Listing 1) is a simple 
text printer that you can adapt to your own needs or use as a 
template for further exploring Macintosh Printing. As always, 
we start with the XCMDBlockPtr as the interface to Hypercard. 
We pass a handle to the text in the first parameter. We could use 
the other parameters to pass formatting information. Parameter 
2, for example, might be set to tell us to draw a border around the 
page. Parameter 3 might contain the margins in page coordi- 
nates. 

The algorithm we use goes like this: Move to the top of the 
page and initialize a rectangle, lineRect, whose height is the 
height of the text to be printed and whose width is zero. Step 
through the text to be printed accumulating words (text separated 
by “white space" or punctuation). If the width of this word plus 
the width of linerect is less than the page width, add this line to 
the current line; otherwise, move down to the next line and add 
the current word to the start of the next line. If any part of the next 
line is below the bottom margin of the page, eject the page and 
reset lineRect's top to the top of the page. 


Scoping 

One of the nice features of writing XCMDs in Pascal is the 
scoping feature of procedures and functions. Pascal allows us to 
define procedures and functions within the main procedure, in 
this case, the procedure "Reporter". This is useful because it 
allows thecallbacks and the nested procedures to share reporter's 
local variables. When we invoke a callback, we don't need to 
pass the parameterBlocPointer. The callbacks can "see" this 
pointer as if it was a global data declaration. Another nice feature 
of writing XCMDs in Pascal is that we don't have to be fussy 
about the entry point. The variable scoping simplifies the 
compiler's job of resolving the entry point. In “С”, subroutines 
follow the main body of the XCMD so that the compiler can use 
the start of the main body as the entry point. 


Step Through 
Reporter first checks the parameter block pointer to deter- 
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mine whether enough parameters were passed. Params[1] should 
be a handle to some text to print. If the handle is NIL, we don't 
have anything to print; otherwise, we open the printer driver, 
allocate a printer record handle (prRecHandle) and fill the record 
with the print defaults. If you wanted to allow the user to change 
the page style (e.g. page orientation), this is where you would 
invoke the printer's style dialog. We'll skip this step for now 
because we want the XCMD to print the document with a 
minimum amount of intervention from the user. 

Next, we put up the job dialog which is the standard printing 
dialog that comes up when you select print from the menu. If 
PRJobDialog returns true, the user clicked the “ОК” button and 
wants us to print the document. 

PROpenDoc associates our printing with a grafport. This 
technique effectively hides the gritty details of printing from the 
application. As long as we draw to the grafPort returned by 
PROpenDoc, the underlying code will convert our QuickDraw 
commands to Postscript for the LaserWriter and to a ribbon- 
eating bitmap for the Imagewriter. 

Once the grafport is opened, we open the first page of the 
document with the PROpenPage and call PrintHandle to print the 
text. PrintHandle manages the opening, closing and ejecting of 
successive pages so when it returns all we need to do is close 
down the printing port with the PrCloseDoc call. Understanding 
this routine will take you a long way to understanding the how 
this printing business works. 

Once we're done printing, we check to see if the document 
needs to be spooled out. Spooled files are saved to disk and 
printed by the call to PrPicFile. This statement insures compati- 
bility with print spoolers that will be looking for picture files to 
print. 

The actual printing is performed by the procedure 
PrintHandle. For the sake of argument, we set the font to nine 
point Geneva. А better approach would be to pass font informa- 
tionas a parameter to the XCMD. GetFontInfo tells us the height 
of the text since that will also be the height of a line on the page. 
We then calculate some rectangles and set the coordinates of our 
lineRect variable. Note that lineRect starts off at the top left of 
the page and has an initial width of 0. LineRect will expand to 
include the width of each word that we add to the line. 

Locking down the text handle allows us to maintain pointers 
to the text. The first pointer, cpos, points to the current position 
in the text while wpos is used to point to the first character in the 
current word. A third pointer, tpos, is used as a “test pointer" and 
will remember the end of the current word. 

The repeat loop in printhandle points tpos to the start of the 
next word (or the first character in the text if we're just starting 
the loop). If tpos is currently pointing to a line termination 


© The Definitive MacTutor, Vol. 4 


character (e.g. carriage return), we print the current line, move 
to the next line and reset wpos to point to the next word. Form 
feeds are handled in a similar fashion except that we eject the 
current page before continuing. 

If tpos points to the nilChar (the ASCII character whose 
value is 0), we've printed all of the text in the input stream so we 
print the line, eject the page and exit the loop. 

The otherwise clause checks to see if the next word in the 
input will fiton the current line. If so, add the word to the line and 
update the pointers accordingly. Since tpos points to the end of 
the current word, setting wpos equal to tpos causes us to “leap” 
over that word. 

If the word doesn’t fit on the line, we first print out the line 
and then move to the next line. After a word is “accumulated” 
into a line, we add the width of the word to the linerect. 

The last routine of note, CalcNextWord, checks to see if the 
next character in the text is a word break character such as a space 
or punctuation. If so, we now have another word to add to the 
output line. 


Summary 

Reporter left justifies the text but you can easily add full 
justification. When you get to the end of the current line (i.e. 
wordsize + linerect > page width) calculate the number of pixels 
that would be needed to “fill” out the line. Subtract the current 
line’s width (right-left) from the page width. If the current line 
is 2000 pixels wide and the page rectangle is 2500 pixels, then the 
number of pixels needed to fill out the line is 500. Divide this 
number into the number of spaces on the line and call SpaceExtra 
to space out the text. 

You'll be surprised out how easy text formatting is with the 
Macintosh toolbox and I encourage you to use Reporter as a 
Starting point for your explorations. 


(KAKKA KAKEK ЖЖ ЖЖ ЖЖ ЖЖ ЖЖ EERE EES ) 


(* File: Reporter.p x) 
(х x) 
(* Prints the entire х) 
(* contents of the container x) 
(* x) 

(х ------ х) 

(* In: perens(1] = handle x) 

P to the text to be printed x) 
x x 
и) 

(* € 1988, Donald Ковсһека, x) 
(*A11 Rights Reserved x) 
(х ————— x) 


(toopnceeeeeeeeeeeoooooooooooooee 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


BUILD SEQUENCE 


pascal Reporter.p 

link -m ENTRYPOINT -rt à 
XCMD=6555 -sn Main-Reporter д 
Reporter.p.o à 

* (Libreries)^Interface.o д 

* (PLibraries)^Paslib.o д 

-о "(xcmds) ^testxcmds 


ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖЖЖХЖЖХЖЖЖ)) 
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($8 Reporter ) 

UNIT Donald. Xoscheka; 
(—INTERFACE—) 
INTERFACE 


USES 
MemTypes, QuickDraw, OSIntf, 
Toollntf, PackIntf, HyperXCmd, 
PrintTraps; 


PROCEDURE EntryPoint(pPtr:XCndPtr); 
(—IMPLEMENTATION—) 
IMPLEMENTATION 


($R-) 

CONST 
CARD = TRUE; 
BKGND = FALSE; 
NILCHAR = $00; 


D; 
9 


LINEFEED = 
QUOTE = 
COMMA = 
PERIOD = $2Е; 
РАКЕМ 


ТҮРЕ 
Str31 = бігіпдіЗ11; 


PROCEDURE Reporter(pPtr :XCndP tr); FORWARD; 


4 


(—EntryPoint—) 


PROCEDURE EntryPointCpPtr: XCmdPtr); 
BEGIN 

Reporter(CpPtr); 

D: 


д 


(—Reporter—) 


Function CalcNextWordCVAR wPtr:Ptr): INTEGER; 


(ЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖ 

ж Given а pointer to а 

word, calculate the 

length of the next word 

in the run. The length 

is determined by adding 

the width of each character 
together until а word 

break is hit. 


ж 


The difference between 
tpos and wpos is always 
one word Cincluding the 
Sticky characters) 


IN: Pointer to text 
wPtr == pointer to NEXT word in 
run Cor NIL if No next word) 


OUT: Width of the next 
word in the line 
XXXXXXXXXXXXXXXXXXXXXXX) 


VAR 


жчемымымы м 6 x иии и o» x« м 
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done : BOOLEAN; PrOpenPageC printer, NIL 2; 
wLen : INTEGER; 


BEGIN (*** Opening & new page yields ***) 
done :- FALSE; (*** а new grafport, reset it ***} 
шеп := 0; TextFont( GENEVA ); 

TextSizeC 9 ); 
WHILE NOT done DO GetFontInfoC FontInfo 2; 
BEGIN CASE wPtr^ OF lineHite := fontInfo.ascent + 
fontInfo.descent * 
CR,FF,LINEFEED,NILCHAR: fontInfo. leading; 
done := TRUE; 

TAB: WITH Prec**.priInfo.rpage 00 
BEGIN BEGIN 
WLen:-wLen*CharWidthC chr(SPACE) ); lineRect.Top := top; 
done := TRUE; lineRect .Bottom:=1ineRect. top 
END; *lineHite; 

lineRect.Right := lineRect. left; 
SPACE, QUOTE, COMMA, PERIOD: MovetoClineRect . left, 
BEGIN lineRect.bottom 2; 
wlen:zwLen*CharWidth( chr(wPtr*)); END; 
done := TRUE; tpos := Pointer( ORD( tpos ) + 1 ); 
wPtr:=Pointer( ORD(wPtr) +1); END; 
END; 

OTHERWISE PROCEDURE NewLine; 

BEGIN (ЖЖЖЖЖЕЖЖЖ ЖЖ ЖЖ ЖЖ 
WLen:-wLen*CharWidthC сһгСиР{г^ )); * Move to а new position on the 
wPtr := PointerC ORDCwPtr) + 1); * page. 

END; окка) 

END; (*** CASE wPtr^ OF ***) BEGIN 

END; (*** WHILE NOT done ***} WITH lineRect DO 

BEGIN 
IF wPtr^ = Ø THEN wPtr := NIL; top := top + lineHite; 
bottom := bottom + lineHite; 
CalcNextWord := меп; МоуеТо( left, bottom ); 
д 
IF bottom > pageHite THEN 
EjectPage; 

Procedure PrintHandleC hand : Handle; printer : TPPrPort; Prec : 

THPrint 2; Right := Prec**.prinfo.rpage. left; 

(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ END; 

* Print the data passed END; 

* as а handle and 

* using the given printer PROCEDURE DrawLine; 

* port. (QOOOOOOOOOOOOOOOOOEEEEEOEOEROEEE EX 

* * Drew the current line pleese 

ж Prints the data into жж) 

ж the current port апа BEGIN 

* handles word wrap and DrawTextC cPos, Ø, num ); 

* page breeks. lineRect.Right := lineRect.left + wordSize; 

* tpos := Pointer( ORDC tpos ) + 12; ( debug ) 

XXXXXEXXEXEEXXEXEEXXEXX) num := INTEGERC ORDCtPos) - ORDCwPos) 2; 

VAR cPos := wPos; 
done : BOOLEAN; wPos := tPos; 
lineHite, END; 
wordSize : INTEGER; 
pageHite, 
pageWidth : INTEGER; (— Reporter —) 
num : INTEGER; BEGIN 
cPos  : Ptr; TextFont( GENEVA 2; 
wPos  : Ptr; TextSizeC 9 ); 

{Роз  : Ptr; GetFontInfoC FontInfo 2; 
lineRect : Rect; lineHite := fontInfo.ascent + 
fontInfo — : Font Info; fontInfo.descent * 


fontInfo. leading; 
PROCEDURE EjectPage; 


(ХХХХХХХХХХХХХХХ ЖЖ ХХХ ХХХ («хх get information about page ххх) 

* Eject the current page and WITH Prec^^.prInfo.rpage DO 

* adjust the rectangle BEGIN 

* accordingly pageHite ‚= bottom - top; 

* pegeWidth := right-left; 

ЖЖЖЖЖЖЖ ЖЖ ЖЖ ЖЖ ЖКХ ) lineRect . top ‚= top; 

BEGIN lineRect.bottom:» top + 
PrClosePage( printer 2; lineHite; 
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lineRect.left :- left; 

lineRect.right := left; 

MoveToC lineRect. left, 
lineRect.bottom ); 


END; 
HlockC hand ); 
cPos := hend^; 
wPos := cPos; 
num := Ø; 
done := false; 
REPEAT 


tPos := wPos; 


CASE tPos^ OF 
LINEFEED, CR: 
BEGIN 
DrawLine; 
NewL ine; 
wpos := tpos; 
END; 


ЕР: 
BEGIN 
EjectPage; 
мроѕ := tpos; 
TineRect.right := lineRect.right + wordSize; 
END; 


NILCHAR: 
BEGIN 
DrawLine; 
done := TRUE; 
END; 


OTHERWISE 
BEGIN 
‘wordSize := CalcNextWord( {Роз ); 
IFC wordSize + lineRect.right ) < pageWidth THEN 
BEGIN 


PROCEDURE Reporter(pPtr: XCmdPtr); 
Coxidoooooooooopboooococo: 

* Print the data that’s 

* passed in as a 


x parameter. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


VAR 

f ieldPtr : Ptr; 

f ieldName : Str255; 

f ieldType : BOOLEAN; 

f ieldData : Handle; 
prRecHandle: THPrint; 
prPort : TPPrPort; 

myS tRec : TPrStatus; 


($I XCmdGlue.inc } 


BEGIN 

WITH pPtr^ DO 

IF CparamCount <> Ø) AND 
(params[1] © NIL) THEN 
BEGIN 


PROpen; 

prRecHandle := THPrintC(NewHandleC 
SIZEOFCTPRINT) 22; 

PrintDefault( prRecHandle ); 


IF PRJobDialogC prRecHandle ) THEN BEGIN 
prPort := PROpenDoc( prRecHendle, NIL, NIL ); 
РгОрепРаде( prPort, NIL ); 

PrintHendleC params[1], prPort, prRecHandle ); 
PrCloseDoc( prPort ); 


IFCprRecHandle^^.prJob.bJDocLoop = 
(РгЕггог = noErr) THEN 


bSpoolLoop) AND 


num := num + INTEGERC ORDCtPos) - ORDCwPos) PRPicFileC prRecHandle, NIL, NIL, NIL, 
); nyStRec ); 
wPos := tPos; 
END END; (*** IF PRJobDialog ***) 
ELSE 
BEGIN DisposHandleCHandleCprRecHandle) ); 
DrawLine; PrClose; 
Кемі ine; 
END; END; (*** paramCount € 0 ххх) 
lineRect.right:zlineRect.right + wordSize; pPtr^.returnValue := NIL; 
) END; (*** PROCEDURE Reporter ***) 
END (** CASE хх). END. 
UNTIL done; 
Listing 1. Reporter.P ~ А text printing XCMD. 
PRClosePage( printer 2); 
HUnlockC hand 2; end Huper Chat ом 
END; (Жете, 
© The Definitive MacTutor, Vol. 4 
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A Nice Chat 

While doing the Sunday crossword puzzle recently, I was hit 
witha very interesting thought. One of the clues in this particular 
puzzle called for a synonym for “small talk”. The answer was 
“chat”. This struck me as odd because in many ways HyperTalk 
is very much the preferred object oriented programming lan- 
guage for the Macintosh. One of the earliest object oriented 
languages, as you know, is called “SmallTalk”. By calling this 
column “HyperChat”, Fred makes a rather obscure reference to 
HyperTalk's philosophical roots. Chat implies a looseness of 
speech, a vernacular that is easy to master. That is exactly what 
HyperTalk is — an easy to grasp interface to the Macintosh 
Toolbox. What HyperTalk lacks in power, it certainly makes up 
for in ease of understanding! 

At the opposite end of the spectrum is Assembly language 
programming. This much maligned language conjures all sorts 
of anxieties in the minds of otherwise fearless programmers. Yet 
most professional programmers will admit that an understanding 
of assembly language can improve one's ability to write efficient 
code in a higher-levellanguage as wellas better understand those 
mysterious looking dumps that one gets when suddenly pre- 
sented with a memory dump from TMON or MACSBUG. 

Worse yet, those of us who choose to work in higher level 
languages provide a great disservice to the assembly language 
programmer by not showing them how to interface with our 
languages. HyperTalk documentation is certainly sparse in 
describing how an assembly language programmer can write an 
XCMD in assembly. 


Assembly Interface 

Istarted writing this month's column hoping to be of service 
to the assembly language programming community. I wasn't 
very far along when I realized that this column offers a second 
service, at no extra charge to the reader. 

The process of showing you how to interface to HyperCard 
in assembly language also introduces the Pascal and C program- 
mer to debugging in Macsbug or TMON (Forth programmers 
take heart: Jórg Langkowski's article in the December, 1987 
issue of Mactutor provides you with the information you'll need 
to write XCMDs; even if you don't program in Forth-like 
languages, you should read Jórg's column; his insights into the 
Macintosh are often astonishing). 

The most important reason to code in Assembly language is 
that itprovides a rich opportunity to improve on the more generic 
code generated by Pascal and C compilers. Consider the follow- 
ing string comparison in Pascal: 
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len : INTEGER; 
Match : Boolean; 
бігі: Str255; 
5іг2: Str255; 


Stri := ‘Hello World’; 
Str2 := ‘GoodBye Cruel World’; 


IF Length(Str1) © LengthC Str2 ) THEN 
match := FALSE 

ELSE 

BEGIN 
Match := True; 
К := 1; 


( assume they will match) 


While Ck <= LengthC Str 12) AND (match) 00 
IF Str ИК] © Str2(k] THEN 
match :- False 


Listing 1. String Comparisons in Pascal 


String compares can be made more efficient than this in 
Pascal. I chose this example for its simplicity. In comparing 
strings, we must consider the end points, if the strings are not the 
same length, they are not equal. If you haven't been program- 
ming in Assembly language, you may not see how this routine 
could be made more efficient. One measure of a program's 
efficiency isacount of the number of bytes of instructions needed 
to execute the program. If you compile listing 1 and dump the 
object code, you would discover that the while loop requires 82 
bytes of instructions to execute. Assembly language program- 
mers know by instinct that 82 bytes is too much code to perform 
a single string compare. 

Anassembly language equivalentof the while loop in listing 
1 can be shrunk by an order of magnitude as in listing 2. If you're 
trying to speed up a particularly slow loop, a few bytes of well- 
written assembler might be just what the doctor ordered. But 
optimizing code is just one reason to familiarize yourself with 
assembly language. А morecompelling reason for the high-level 
language is that an understanding of assembler will help you 
make sense of your TMON or MacsBug dumps. 


Аб, №1 point to the 2 strings 


Move.b (А )+, 01 ; get the length of string 1 
Move.b СА1)+, 02 ; get the length of string 2 
Стр.) 01,02 ; ere they the same length? 
Beq CompareChars ; yes, go ahead and compare them 
Move #0, 00 ; Set the result to false 
Вга боле ; end exit 

CompareChars ; compare Str 1<-Str2 
Cnp.b CAB)+,CA1)+ ; do the characters match? 
Beq Done ; yes, see if we’re at end of 


© The Definitive MacTutor, Vol. 4 


string 
Dbra D1, CompareChars 
Move 81, D ; they match, set the result true 


DONE sne 00 ; Result is true if strings match, 
false otherwise 


Listing 2. String Compare in Assembler 


Entering XCMDs 

The real trick to writing an XCMD in assembly language is 
understanding that HyperCard expects to see an XCMD that was 
generated by the Pascal compiler. This implies that parameters 
are pushed on the stack from left to right and that subroutines are 
responsible for removing the pushed parameters from the stack. 
XCMDs receive only one parameter so the push order isn't 
important. What is important is remembering to remove that 
parameter from the stack before returning to HyperCard. Listing 
3 is the assembly language interface for XCMDs. The fields in 
the paramBlock record are identical to the Paramblock record in 
Pascal or C. 

On entry to a subroutine in assembly language, the last item 
on the stack is the return address of the calling routine. Normally, 
when we are done with the subroutine, an rts (return from 
subroutine) instruction will pop this return address off the stack 
and into the Program Counter resuming execution at the instruc- 
tion pointed to by that location. This won't do for Pascal routines 
since convention dictates that we also remove the parameters 
from the stack. One way to do this would be to pop the return 
address into a temporary register, say DO, remove the parameters 
from the stack by adding the size of the parameters to the stack 
pointer and then pushing the contents of DO onto the stack and 
executing an RTS. A more efficient method exists: Pop the 
return address into an address register, say А0. Unbias the stack 
parameters by adding 4 to the stack (the size in bytes of the 
parameter block pointer). Finally, since register AO contains the 
return address, execute the Jmp Indirect instruction on А0: J mp 
(А0). 

Globals п XCMDs 

If your XCMD requires local variables, you're going to need 
a place to store them. Assembly language XCMDs bear the same 
restriction placed on high-level languages: you don't have access 
to the globals. A simple solution would be to allocate a handle 
large enough to store all your globals and keep that handle 
available іп an address register. This works fine if the data is very 
static but not very well otherwise since you could easily run out 
of registers while manipulating even a small number of handles. 
Pascal and C use a more efficient approach, one that you've 
already seen if you've done any debugging in TMON or 
Macsbug. 

On entry to the subroutine, we know that the stack pointer, 
register А7, already points tothe nextavailable space on the stack 
(the bottom of the stack). Why don't we allocate our data on the 
Stack by pointing an address register, say A6, to the bottom of the 
Stack, subtracting the number of bytes that we need for our locals 
from A7 effectively growing the stack by the amount we need 
(the stack grows downward). Now Аб points to our local 
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XCMDBIKkPtr 


ReturnAddress 
Old A6 


Stack Frame 


XCMDBIkPtr 
ReturnAddress 


Stack on Entry to the XCMD 


8(А6) 
4(A6) 
AG 


A7 


A7 


Stack After Link 


Figure 1. Link allows you to allocate storage on the 
stack. 

variables and A7 continues its role as stack pointer below our 

local stack frame (figure 1 ). 

The process of creating a stack frame can be performed with 
one assembly language instruction: link. Used judiciously, the 
link instruction buys us a whole lot more: it saves the old value 
of the address register and gives a reference point to the parame- 
ters passed by the caller. 

By executing link A6,#LocalSize, before doing anything 
else, we set up up a stack frame at the stack bottom. If stacksize 
were set to Zero, we wouldn’t actually allocate any stack space for 
globals, but the instruction would still provide a payback. Be- 
cause nothing else was put on the stack between the call to this 
routine and our link instruction, A6 also doubles as a pointer to 
our parameters! First, 0(A6) contains the previous value of Аб 
(can you think of anything this might be useful for?), next 4(A6) 
is the return address, and 8(A6) is the paramblock pointer passed 
to us by HyperCard. By putting 8(A6) into A3, we save the 
pointer to our parameters in an address register. 

The offsets defined in the parameter block equates now 
become offsets off A3 for each field. The first field in the record 
is paramCount(A3) the count of the number of parameters in the 
params array. Accessing the handles in the params array poses 
another question. The first handle in the array is at params(A3). 
Getting to the other handles in the params array requires a 
straightforward application of arithmetic. By definition, handles 
occupy 4 bytes in the Mac. Any array element, i, is at offset (i- 
1)*4 byte in the array. We subtract 1 from the element number 
because array indices count from 0 not from 1. If we putthe array 
index into DO, subtract 1 and multiply by 4 we have the offset 
from the beginning of the array. All we need to do is add this 
number to params[A3] and we have the handle. The 68000 has 
Just an instruction: indexed addressing with offset. Here is how 
this instruction can be used to get the third parameter in the list: 


Moveq #3, 09 ; Access the third peremeter in the list 
Sub .w 81, 00 , arrays count from 0, not 1 

As] .w 82,00 ; shift left by 2 is seme as multiply by 4! 
Моуе. 1 рагатз(АЗ,00.м), AØ ; А0 now holds the third handle 


Since stack frames are oriented from the highest memory 
location they occupy to the lowest, local variables are always 
referred to by negative offsets. In Pascal, the following declara- 
tion 
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VAR 
nyInt : INTEGER; 
myLong : LongINt; 


myRect : Rect; 
would have the following counterpart in assembly language: 


nyInt EQU -4 ; locals start at offset -4 in the 
{гате 

myLong EQU myInt-2 ; Integers are 2 bytes 

myRect EQU myLong-4 ; longs are 4 bytes 

LocalSize EQU myRect-8 ; rectangles are 8 bytes. 


LocalSize is equal to 14 bytes. The stack frame is set up to 
read: 
LINK Аб, *LocalSize 
Move.w (А0),00 

If you’re having a bit of difficulty with this material, try 
writing a simple XCMD in Pascal or C and disassembling it in 
TMON or Macsbug. You can do this by invoking the Debugger 
call as the first statement in you XCMD. 


; create the local variable pool. 


Exiting the XCMD 

Leaving the XCMD requires a little house cleaning. First, 
we restore the registers that were saved onto the stack. Next, we 
execute an unlink (UNLK) instruction to undo the last Link 
instruction. At this point, the stack looks just like it did when we 
entered the XCMD. More importantly (A7) is the return address 
of the calling routine. Popping this value into AO allows us to 
save the return address in a safe place so that we can remove the 
parameters from the stack. We know how much space the 
parameters take. The stack contains only one parameter, 
XCmdBikPtr, whose length is four bytes. Adding 4 to А7 shrinks 
the stack to the right size. Now all that’s left is to Jmp to the 
location pointed to in AO and we're done! 


Conclusion 

If you're already programming in assembly language, this 
article is enough to get you started with XCMDs, especially if 
you're not familiar with Pascal calling conventions. If you're a 
Pascal or C programmer, the above discussion should help you 
to debug your code by explaining some of the assembly code you 
may have been looking at in TMON or Macsbug. In any case, 
understanding how compilers take your statements and convert 
them into machine executable code is a great way to learn more 
about the inner-workings of your programs and those seemingly 
mysterious bugs that just are not obvious in your Pascal or C 
source code. Hopefully, I’ve been able to fill some gaps in your 
debugging skills with this information. If the information in this 
article was useful, please let me know, I'll be happy to offer more 


information on assembly language and debugging techniques. 
“ХХХХХХХХХХХХХХХХХХХХХХ ХХХ ХХ 


:X File: SimpleXCMD.a 


P 

m 

27 

;* А simple ХОМО written іп 
;* Assembly language to show 
;* how XCMDs are written in 
j 
; 
j 
Г 
) 


зе % % м 2 м 


:X assembler.. 
Ж M ——— Ж 
:X By: Donald Koscheke * 


‚х Date:16 July, 1988 x 
“ХХХХХКХХХХХХХКЕХХХХХХХХХХХХ ХХХ 
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j 
;* Build Sequence 

“Ж 

;* asm -w SimpleXCMD.a 

;* link -rt ХСМ0= 1200 -sn Main=SimpleXCMDo 
М SimpleXCMD.a.oo 

;* -o “YourStackName” 
рыны 


;***ParamBlock structure *** 
paramCount EQU 0 

params EQU 
returnValue EQU 
passF lag EQU 
entryPoint EQU 


paramCount+2 
params+( 16 * 4 ) 
returnValue * 4 
passFlag + 2 


request EQU entryPoint + 4 
result EQU request + 2 
inArgs EQU result + 2 
outArgs EQU inArgs + С 8 * 


4) 
pBlkSize EQU outArgs + (4 * 4 ) 


LXX a> T S: xxx 

;*** THE LOCAL VARIABLES — *** 
;*** (WILL GO ON STACK) xxx 
;*** Note that the stack frame *** 
;*** counts backwards from дй 55% 
;*** so that the value of XXX 
;*** LocalSiz will always be — *** 
;*** negative Xxx 
LOCALS EQU Ü 

LASTLOCAL EQU LOCALS 
LOCALSIZ EQU LASTLOCAL 
pees — ERE QUON xxx 

SimpleXCMD MAIN EXPORT 


QOCOOOOODOOOODDODOOOOOOOEEXEEX XX 


= Return Address 
= ParamBlockPtr 


‚ж Link Аб to create а stackframe 


;* that points to these vers. 
‚ ХХХХХХХХХХХХХХХХХХХХХХХХХЖХ ХХ 


;*** Set Up Stack Frame 
LINK A6, "LOCALSIZ : Size of the local frame 


MOVEM.L D5-D7/A3/M, -(SP) ; ; Save some registers 
;*** Get Pointer to paramblock 

MOVE.L 8(Аб), АЗ ; Point to parameters 

CLR.L returnValueCA3)  ; set to “empty” 

TST.W paramCount(A3) ; Any Parameters? 

BEQ DONE ; no, just return 


;*** Insert your code here. If your XCMD doesn't take any 
;*** parameters eliminate the atest on paramcount ... 


DONE ;XX** Prepare for Return to HyperCard 
MOVEM.L (SP)+,D5-D7/A3/A4 ; restore registers 
UNLK A6 ; wipe out stack frame 
MOVE.L CAT)+, Ай ; get the return address 
ADD.L 84, AT ; unbias the stack 
ied САЙ) ; return to HyperCard 
D 


Listing 3. SimpleXCMD in Assembly Language 
end HyperChat 


Sell 


carae 
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HyperChát!M 
The Vertical Market 


on A ei i 
— HyperEditorial 


HyperCard: what will the future hold? 


HyperCard is just over a year old; some people say that it's 
not the panacea that everyone thought it was; others say it's the 
best thing since sliced bread. 

Whatis it being used for? We don't see hordes of stackware, 
in the shelves at the local computer store, yet do we? Well it 
seems to me that Apple was right with it’s obscure placement of 
HyperCard as System Software. Does HyperCard really fall into 
this category? HyperCard is used as controller for sound digitiz- 
ers, MIDI devices, CD-ROM's, Laserdiscs, and Scanners. Italso 
allows other programs such as Macromind's Videoworks to run 
as drivers. It can act as a finder replacement and much more. 

With the introduction of MacPaint, the rest of the world 
started to play catch-up to develop paint programs. We shall see 
programs that have similarities to HyperCard emerging. Once 
again Apple was not that interested in the sales of MacPaint, it 
used it to "Change the World one Computer at a time" and drive 
it's market forward. It is interesting that both programs are by the 
same author, namely Bill Atkinson. HyperCard is not the “be all 
and end all”; it is merely the start of the next generation. We 
should call it the *HyperGeneration" or “MultiMedia Genera- 
tion", just as MacPaint was the forerunner of the "Graphic 
Interface Generation" 

College curricula are already offering courses in Hypertext 
and MultiMedia. We don't hear about the most interesting 
HyperCard applications because they are vertical. A few ex- 
amples: 

Techniques in surgery of the hand (utilizing scanned 
images and videoworks) 

The electric cadaver(using laserdisc) 

Genetic maps and molecular biology 

Floorplans of large automotive factories 

Artificial archeology. 

This list shows the diverse nature of HyperCard. It is 
possible now to fill alot of previously hard to access niches. Well 
what kind of vertical market opportunities are out there? Just look 
around; A catalog of parts and part numbers for regional offices, 
Training disks for employees. How do you get into developing 
vertical market applications? We have seen that the market 
defines that the content of a stack in particular (naturally a good 
interface is vital) is important, and, if you сап produce a stack that 
is "Educationally Entertaining", all the better. For example, you 
are a HyperCard developer and a scuba diver; you might get 
together with an instructor to make a stack to teach diving. You 
can do it simply(text and some graphics), or animated graphics 
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or videoworks animation(color and sound); if it gets too big, put 
it on a CD-ROM. You can even go as far as using video and 
putting it onto laserdisc. The extent and depth you wish to go to 
depends on the usual factors, time and money. The beauty of 
HyperCard is that if you only do a simple stack it can easily be 
expanded by someone else. There are literally thousands of 
opportunities waiting in the vertical market arena. I was recently 
in the Serengeti Wildlife Reserve in Tanzania Africa, on a 
Photographic Safari and I meta scientist that studied leopards. He 
told me he had all this video footage of the leopards; how they kill 
their prey and drag them into the tree tops to eat them, plus stills 
of bone fragments, and tooth pressure data obtained from the 
bones etc. He was saying wouldn't it be wonderful if you could 
put all this data from different media together and present it. 
When I told him about HyperCard and what it can do he nearly 
fell over backwards and told me I was a godsend. So you see it 
is not hard to find vertical markets even when you are on 
vacation. 


A really good book that gives great insight into planning a 
HyperCard project is Applied HyperCard: Developing and 
Marketing Superior Stackware by Jerry Daniels and Mary Jane 
Mara itis published by Brady Software and comes complete with 
a disc. 
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figure 1. 

You may remember the authors made a stack called MacTV, 
a type of future look at what TV will be like when controlled by 
acomputer. They take you from basic concepts of HyperCard and 
hypermedia through project management to marketing and dis- 
tribution. The appendices list distributors, publishers, press 
contacts, user groups as well as a hypertalk glossary. This is a 
book that is ideal for the developer who is thinking of going 
commercial. 
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figure 2. 
As mentioned earlier Apple has released a development 
package for Videodisc. It comes complete with drivers for most 
players, or you can write your own. 


Ld 


$ File Edit Go Tools Objects 


VideodiAc * 
Players? index? 
Cables? Controllers 

Interactive? 


Getting Started 


Every Stack Needs... Index Maker 


Video Notebook 


Controllers & Buttons Set Player Type 


1ef2 C? 


figure 3. 
It also gives some great ideas for interface design with 
controllers. Such as the simple controller that looks like the 
control panel on a Videodisc player. 


Video Browser Panel (7) нер | ЕЕ Toolkit Contents | < Return 


Search 
end Play] | 


| Set Pleyer — 


figure 4. 
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The human interface group at Apple did a great job with the 
gesture controller, when you are watching the video you can go 
back and forward using the mouse without taking your eyes off 
the screen. This package is well worth getting (through APDA). 
The investment in Videodisc technology is not that expensive at 
well under $1000 for player and monitor. 


Gestural Controller |0) Help | ETT ToolKit Contents | <I Return 
5сап/ es Бау Бер Siop Step Forward E Scan 


=N i 
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— 
figure 5. 
—HyperBugs 
Dear HyperEd, 


I have found an interesting bug (or maybe itis just a feature?) 
in HyperCard (versions 1.2 as well as 1.2.1, system version 4.3, 
finder 6.0 under or without multifinder 1.0). 

From any stack, open the message box, then 

1. Hide card window (from then, HyperCard loses control of 
your keyboard, even in blind-typing mode). 

2. Hide the menubar and finally; 

3. close the message box; from that point , the Mac is hung 
and I could not find any means to get control back other than 
rebooting. Even under multifinder, and using macsbug is of little 
help. 


Sent in by Jean-Pascal J. Lange 
Commission of the European Communities 
Joint Research Center 


—ScriptTips 

This month I have written a script that will show all the 
hidden buttons and fields. I have used a single button and 
depending where you click it, it will do that operation. I will leave 
it as an exercise for you to try to improve the script so that it 
remembers which ones were originally hidden. This should be 
easy for the people that followed the AutoHyperEdit evolution. 


— ooooShowHiddens by Fred Stauder Oct 19880000 
- Hold the mouse down on cdBtn to show hidden card buttons 
— it will show all of them or until you release the mouse 
button 


on mouseDown 

get trunc((Citem 1 of the clickloc) - Citem 1 of the rect 
of me)) /^ 

(CCitem 3 of the rect of ме) - Citem 1 of the rect of me)) / 
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end if 
if it is 0 then end mouseDown 
repeat with 1=1 to the number of card fields Non-Comercial use only - A11 Rights Reserved | 
if the mouse is up then exit repeat Fred Stauder, HyperCard Editor, (HyperChat) MacTutor 
show cerd field i --- ooooShowHiddens by Fred Stauder Oct 19880000 
end repeat 
else if it is 1 then š < 
$ File Edit Go Tools Objects 
LS MALAMLAML.IIL 1 HERR 


repeat with 1=1 to the number of background fields 
if the mouse is up then exit repeat 
Show background field i 


end repeat 


repeat with ізі to the number of card buttons 
if the mouse is up then exit repeat 
Show сага button i 

end repeat 


else if it is 3 then 


repeat with i21 to the number of background buttons 


if the mouse is up then exit repeat См! 
show background button i z figure 6. (55272, 
end repeat Have a HyperChristmass from the HyperChat Team! 
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MPW Workshop 


Using Consulair C & TML in MPW 


William Powell is a candidate for a doctorate degree in 
Geophysics from the University of Utah, and is responsible for 
the design, documentation and delivery of software used to 
operate the Voyager spacecraft while a technical assistant at the 
Jet Propulsion Laboratory in Pasadena. He is presently doing 
research in the thermal physics of the Colorado Plateau 


Iam highly resistant to changing development systems, but 
after after all the fuss over MPW and reading J. West's MacTutor 
article [vol. 3, no. 2] on the resource tools in the Macintosh 
Programmer's Workshop (MPW), I decided that I couldn't live 
without this product. Along with everyone else, Ihave frequently 
experienced frustration from the limitations of earlier resource- 
building programs. I have also wished for a programmable shell 
on my Mac for certain data processing operations which I used 
to perform very conveniently on Unix systems. So I broke down 
and purchased the АРБА release of MPW, and a hard disk to hold 
it. Ihave subsequently made some efforts toward integrating the 
MPW shell with older applications. I hope that some of my 
discoveries and command scripts may be generally useful to 
others who are using applications with MPW. 

The programmable shell and tools of Apple's Programmer's 
Workshop (MPW) give anew dimension of flexibility to Macin- 
tosh development. The MPW brings the Macintosh a long step 
closer to the capabilities of more established development sys- 
tems such as those available in the Bourne shell or C shell of Unix 
systems. This necessarily means that MPW has made a long step 
awayfrom earlier Macintosh application-type development 
systems. MPW introduces a new class of compiled program, the 
MPW Tool, which interacts with its shell more intimately than 
earlier applications interact with the Finder and similar shells. 

Bridging the gulf between the MPW shell and earlier Finder 
application development systems is the topic for this article. I 
will present examples for my development systems of choice, 
Consulair MacC and TML Pascal. There are three core issues in 
Joining the MPW shell and application-type development sys- 
tems. First is the problem of conveniently running applications 
in concert with programmable shell scripts and the automatic 
make utility. Second is the problem of writing a new class of 
program, called a MPW tool, using a development system which 
does not contain provision for such a thing. Third is object file 
compatibility with the MPW standard. This article will concen- 
trate on the first item. 

Many of the techniques discussed here are relevantto almost 
any programming of the MPW shell and will be of interest even 
if the reader does not need the sample command scripts for 
running development applications. This article includes ex- 
amples of advanced MPW editor commands, examples of com- 
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applications. 
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plicated shell quoting problems, and examples showing the use 
of shell variables. Information here about launching applications 
from the shell and about the distinction between windows and 
files is not found in the MPW Reference document. Ialso use the 
Make tool three times in this article — only one time involving 
building a program! I will assume that the reader is slightly 
familiar with the shell and has access to the MPW Reference 
document for more detailed background. 


Motivation 

Why did I make the effort to mix older development systems 
into MPW when an assembler and C and Pascal compilers are 
already being distributed? One consideration is budget; itis hard 
to justify the cost of anotherC or Pascal compiler when the ones 
Ihave actually work just fine. Source portability is never perfect 
across Macintosh compilers and I haven’t felt too anxious about 
converting yet another program to yet another compiler. Also, as 
noted by F. Alviani [MacTutor vol.3, no.4] the MPW system 
contains its own quirks, such as segmentation established in 
compilation rather than in linking. 

There may be hardware considerations as well. The MPW 
documentation suggests that the MPW C compiler needs every 
byte of a IM machine. This should be a serious consideration for 
those of us who develop in C on the pre-1987 Macs. It is good 
that the MPW system is forward looking in terms of newer 
machines, but many of us can't (or won't) upgrade our hardware 
and software as frequently as it is offered to the market. 

On the other hand, the MPW shell offers the most flexible 
programmable shell and scripting abilities available for the Mac. 
The text editing features of the MPW shell are quite convenient, 
and more significantly, programmable. The first complete and 
extendable set of resource tools resides in the MPW. The 
programmable shell allows you to do things “уош way" instead 
of locking you into someone else's concept of good development 
tools. It also provides a suitable environment for many less 
human-interactive data processing needs. 
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So there are excellent reasons to add the MPW shell to the set 
of tools available to most Mac programmers and there are good 
reasons for some of us to keep our older development systems. 
The puzzle now is to find convenient ways to use the power and 
flexibility of the MPW shell in conjunction with older Finder- 
based development applications which have no facility to inter- 
act with the shell. 


Applications and the MPW shell 
The MPW shell is primarily a command interpreter, which 


parses lines typed by the user and interprets them as some sort of 
instructions to be performed by the computer. A simple com- 
mand normally appears as a line of text. The first word on a 
command line is the name of the command to be performed — 
conventionally a verb describing the action performed (e.g. 
Count, Make, Delete, Open, etc.). Subsequent words on the 
command line are arguments which either indicate objects of the 
action (e.g. files to be read or written) or specify modes or options 
for the action (choices which would be selected with menus or 
modal dialogs in Macintosh applications). As with most pro- 
gramming languages, syntax is available to produce compound 
command statements from several simple commands as de- 
scribed here. The shell also allows the setting and testing of 
values of variables. When I refer to variables in the following 
discussion, I will use the notation (variableName). 

Commands are implemented in four different ways. Some 
are built into the code of the MPW shell application itself. Some 
are separately compiled programs called “MPW Tools" which 
run from within the shell, much as desk accessories run from 
within other applications. The name of a “TEXT” file containing 
one or more lines which the shell can interpret as commands may 
itself be used as a command. Finally, for compatibility, the 
authors of the MPW shell allowed the names of Finder applica- 
tions to be used as commands which cause the applications to 
start. 


Applications and the Finder environment 

Normally when an application runs, it starts off with a nearly 
clean slate. Itinitializes most of the ROM toolbox managers. The 
only high-level data in the application areas of memory which are 
normally available to an application are any resources which 
were stored on the clipboard before the application was launched 
and the “Finder Information”. The Finder Information structure 
is essentially a list of files to be opened or printed by the 
application. For example, when a user uses shift-clicking to 
select several documents and an application in the Finder, the 
names of those documents selected by the user are passed to the 
application in the Finder Info structure. 

There are no standards for passing any other type of informa- 
tion from the launch environment to the application. Some 
development systems and other systems of several applications 
use “chaining” instead of “launching” [Inside Macintosh v. II, ch. 
21, which allows resources and other data to be passed in the 
application heap. Unfortunately this requires knowledge of 
coding details of the applications, and will not be suitable for 
integrating an arbitrary application with the MPW shell. Appli- 
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Outer-most shell 
variable scope 


First nested level 
of variable scope 


Command file 
"FileA" 


4 VarA is undefined 
# VarB is undefined 
4 VarC is "String Val" 


Set VarA "Redefined" 
Set VarB " local string" 
Set VarC "Changed" 


Set VarA "the String" 
4 VarB is undefined 
Set VarC "String Val" 
Export VarC 


FileA 


# VarA is "Redefined" 
4 VarB is "local string" 
% VarC is "Changed" 


% VarA is "the String" 
# VarB is undefined 
# VarC is "String Val" 


Figure 2. The ins and outs of MPW 
shell variable scope. 


cations have been designed under an implicit assumption that all 
information about operational modes was to be provided interac- 
tively by a human user. This leads to the most common impedi- 
ment in using applications as MPW commands — it is very rare 
that applications can complete their job without some human 
intervention (at the very minimum it is usually necessary for the 
user to select “Quit” from the application menu to return to the 
shell). This is unfortunate, because the function and mode of 
applications such as compilers may be fully defined at the time 
they are invoked, and the user intervention becomes an unneces- 
sary redundancy. 

In spite of the inconsistency between the highly interactive 
user interface of applications and the more mechanized program- 
mable MPW shell, it is possible to develop procedures to inte- 
grate shell commands and applications (particularly develop- 
ment systems) with reasonable success. While it is not possible 
to eliminate human intervention in the applications, we can 
minimize the actions which the user must perform. Some of the 
tips in this article might be viewed as an ad hoc system of “MPW 
interface guidelines" to this end. 


Applications and MPW 

As mentioned above, the MPW shell allows us to launch an 
application by invoking its name as acommand. MPW maintains 
a shell variable called (Commands) with a list of directories 
(folders) to search for commands. Ш the application resides 
somewhere in this command search path list, merely the filename 
of the application is sufficient as a command. Otherwise the full 
pathname, with the volume and all subdirectories leading to the 
application's resource file must be used as the command name. 

The MPW shell provides the standard mechanisms for 
putting resources on the clipboard or retrieving them from the 
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clipboard. So passing data to or from ап application on the 
clipboard can be performed without any special considerations. 
The only other information an application might expect from its 
launch environment is a list of files in the Finder Information 
structure. The MPW shell has provided a standard method to 
pass this information. Filenames which are to be passed in the 
Finder Information to the application are simply listed as argu- 
ments on the command line following the application name. 
Thus, we can fully configure the standard application launch 
environment using mechanisms explicitly provided by the shell. 


Example 1. Launching application with Finder Info. 

There may be a number of applications which are commonly 
launched by the user from within the shell; this will be especially 
true if the user has completely replaced the Finder with the MPW 
Shell. I have found it convenient to add а “Вип” menu to the 
MPW shell, using the shell command *AddMenu". This allows 
selection of my most commonly used applications via menu 
choices. Such a menu is illustrated in Figure 1. 

Mostof the items in this menu are straightforward; selecting 
the menu item simply launches the application because the 
command field of the “AddMenu” command consisted only of 
the filename of the application. The last item on the menu, 
"Word-Paint" is more interesting because it launches a Switcher 
set of MS Word and SuperPaint. This menu selection launches 
the application Switcher and passes a Switcher document in the 
Finder Information. The command line to perform this appears 
as an argument in the ““AddMenu” command which created the 
menu item: 


AddMenu Run Word-Paint 9 
'"XP40:Word:Switcher XP40:Word:Wordd+SuperPaint’ 


The word AddMenu is the command which will add this 
item to a menu in the MPW shell. Three arguments follow the 
command name. The first argument is the word “Вип” which is 
the name of the menu we wish to affect. The second argument 
"Word-Paint" is the text of the item being added to the menu. The 
curly-d (0) is followed immediately by a return and signifies that 
the command continues on the following line. The third argu- 
ment is the text appearing between single quote marks. This is 
the command which will be executed when the menu choice is 
selected. The command consists of two words separated by a 
space. The first is the full pathname of the application to launch 
(Switcher) and the second is the full pathname of the document 
to pass to the application in the Finder Information. The docu- 
ment name in the Word folder is ““Word+SuperPaint”: the extra 
curly-d is a literal quote of the following character, “+”. This 
quote is necessary because the unquoted “+” symbol is used by 
the shell as a metacharacter implying certain filename matching 
rules. 

When we select this menu item, the MPW shell closes and 
Switcher is launched. Switcher then automatically opens the 
document “Word+SuperPaint” which in turn tells Switcher to 
launch those two applications. When we quit from both applica- 
tions and the Switcher, the MPW shell will be restarted. 
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Of shell variables and search paths 

A MPW shell variable is a unique symbolic name that 
represents storage for a string of characters. Shell commands are 
available to set the value of a variable, test values, and shell 
syntax allows the value ofa variable to serve as text ina command 
simply by referring to the variable name. The “Evaluate” 
command also allows arithmetic operations on strings which can 
be interpreted as integers. Variables in the shell are entirely 
analogous to variables in other programming languages. The 
following examples will use shell variables extensively, so a very 
brief review of the MPW rules on variables will be helpful. 

Values are assigned to variables by the “Set” command: 

Set УагМапе "the String value" 

The value of a shell variable is substituted in acommand line 
by enclosing the variable name in curly braces, (). Thus, when 
we follow the Set command above with the command: 

Echo  (VarName] 

the output printed is: 

the String value 

A variable is defined when its name is first encountered by 
the shell. The Set command can be used to assign a value to the 
variable; if the first occurrence of the variable is in a command 
other than "Set", the null string is used as a default value. The 
only exceptions to this are some predefined variables which are 
created by the shell when it is launched [ MPW Reference 
Manual, Table 3-2]. 

The scope of variables is an important consideration in 
designing shell scripts. Normally, the value of a variable is 
maintained only within the command file where that variable is 
defined. For the purposes of this discussion, we include com- 
mands typed by the user in windows created by the shell as the 
outermost scope. When a command file is executed by invoking 
its filename as a command, a new nested level of variable scope 
is created to correspond to the command. Variables definedat the 
level where the command file is invoked are not defined within 
the innerexecuting command file. Conversely, variables defined 
within an executing command file are no longer defined when 
that command file terminates and control returns to the level of 
invocation. Variables VarA and VarB in Figure 2 offer examples 
of these scope rules. 

Two important commands modify these rules of variable 
scope. Using the “Execute” command to run a command script 
file, instead of using the filename as a command, causes the 
commands in the file to operate within the current scope rather 
than creating a new level of variable scope. The “Export” 
command causes a variable and its value to become available to 
script files which are nested within the level containing the Ex- 
port command. Using Export to pass the values of variables into 
nested command scripts is analogous to passing subroutine 
arguments “by value” in languages such as C and Pascal. 
Changes in value of exported variables are therefore not passed 
back out to the enclosing command file. The variable VarC 
shown in Figure 2 illustrates the behavior of an exported variable 
in a shell script. Another somewhat anomalous problem of 
variable scope occurs when applications are started from shell 
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scripts, but Пеауе further discussion of this 
to one of the examples below. 


ES 


Libraries 


га 


Standard search paths for files 

Many programs need to be able to find 
and use auxiliary files to process their input 
and generate their output. For example, 
compilers often need to be able to merge 
*include" files containing system defini- 
tions with the current source file, and 
linkers need to be able to find object code 
libraries when constructing programs. 
Searching a large hierarchical file system 
for these auxiliary files may take a prohibi- 
tive amount of time, so it is conventional to 
supply a “search path" — a directory or a 
small list of directories where the desired 


Rincludes TMLPas 


MacC 
C Includes Includes Rels Asm Includes 


C.Path. Template 


Alnciudes Runtime.o 
and other 


MPW libraries 


files are most likely to be found. 

The MPW development systems use 
shell variables to store search paths for 
various items. The MPW variables are 
listed in the top section of Table 1 (and are 
also discussed in the MPW Reference 
Manual). Some of the variables (marked 
with “S” in the table) contain the full pathname of a single 
directory to be searched; other variables (marked “1.” in the 
table) contain a list of full pathnames of several directories, with 
the pathnames separated by commas. Using this system, changes 
of the directory structure or locations of files is accommodated 
simply by adjusting the values of these variables. 

Other development systems, such as TML Pascal and Con- 
sulair MacC, also need to address this “‘search path” problem. 
These systems use special resource files in the System Folder to 
save the search directories they need, and provide software 
allowing the user to modify the stored paths. In the rest of this 
section, we try to integrate these two methods of specifying 
search paths. We want to follow the MPW standard to save 
search paths in shell variables (Table 1, lower part) and then use 
these variables in shell scripts which will create the search path 
resources expected by the applications. Figure 3 shows a 
directory pattern for libraries, and indicates what folders are 
listed in various shell variables from Table 1. 

Example 2. TML Search Paths. 

When TML Pascal or Linker need to find include files, 
compiled symbol tables for “Uses” or object file libraries, they 
first look in the directory containing the source file being proc- 
essed. If the file is not found there, up to five other directories are 
searched. The full pathname of each of these five directories is 
saved as a resource (type ‘STR ‘) in the file “Paths File” in the 
System Folder. The TML package includes a desk accessory 
which provides a dialog where the user types directory pa- 
thnames for the “Paths File". 

Following the MPW model, the desired search paths are 
saved as the values of shell variables {TMLPasLib} and 
(TMLPasInc). We must now write the pathname strings from 
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Figure 3. Sample directory arrangement for development 
systems. Pathname to folder A is maintained in shell 
variable {Libraries}; to folder B in {MacCLib}; to folder C in 
(TMLPasLib). 


these variables as the resources in the “Paths File". The obvious 
way to do this is to use the pathname text from the variables to 
generate an input text file for Rez, the MPW resource compiler; 
Rez, in turn, will create the ‘STR ‘ resources. Shell script file 
*MakePPath", in the listings following the article, accomplishes 
this. 

MakePPath opens two temporary windows for use as scratch 
files. Into one window, the pathname list from shell variable 
( TMLPasInc } is written, so that it can be parsed with shell editor 
commands. The second window, TMLPathOut, is where we 
create the input for Rez. In MakePPath, we write the HFS path 
from variable (TMLPasLib) into string resource 128, and the 
first four HFS paths from (TMLPasInc] are written into re- 
sources 129 - 132. If (TMLPasInc) contains more than four, only 
the first four are used. 


Teble 1. 


Shell variables for file search paths. 
System 


Ver Neme List * Purpose 


Libraries 
AIncludes 
RIncludes 
CLibraries 
CIncludes 
PLibrar ies 
PIncludes 


MPW runtime libraries 
MPW Assembler header files 
Type definitions for MPW Rez 
MPW С` object libraries 
MPW C header files 
MPW Pascal object libraries 
MPW Pascal include files 
MacCL ib Folder containing Consulair 
objects, headers in sub folders 
TML Pascal object libraries 
more TML object libraries 

and includes 


TMLPasL ib 
TMLPasInc 


* § means variable contains only one directory to search 
L means variable contains comma-separated list 
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Тһе main novelty in MakePPath is the loop which breaks the 
comma-separated list of paths from {TMLPasInc} into individ- 
ual paths using the MPW editing and selection commands; this 
could also be useful in breaking down other lists in MPW 
variables. Let's consider the editor commands which do this. It 
is assumed that 1)the list of paths has been written as a single line 
in the file named Tmpfil, and 2)none of the directory names in 
any of the paths contain a comma. 

Before entering the loop, we move the selection in the 
Tmpfil window (the insertion point) to the beginning of the file, 
before the first character. 

Find * Tmpfil 

Then we loop until we find all the paths in the list. The first 
selection we make inside the loop is: 

Find SA:A/,/ Tmpfil 

This selects text from the character after the previous selec- 
tion to the character preceding the next comma. This selection, 
if it exists, is a valid path, and we can use the notation Tmpfil.§ 
to refer to this selection. After we use this selection, the 
command: 

Find SA:SA!1 Tmpfil 
selects the comma following the interesting text. This way when 
the loop repeats, our next string will not begin with an extraneous 
comma. If the selection at the beginning of the loop could not be 
made, then we have reached the last path (which of course will 
not end with a comma) or there was no text in the variable to 
begin with. The command: 

Find SA: Tmpf il 
selects all the text to the end of the file and so selects the last path, 
ifitexists. Since all commands in the shell, including Find, return 
a status value, we are easily able to test whether each of these 
selections is successful. 

The script file MakePPath is a little more elaborate because 
it must use only the first four strings from the variable. Also it 
must write null strings into the ‘STR ‘ resources when fewer than 
four are specified. After MakePPath has run, the ‘STR * re- 
sources it created must still be turned into paths used by the 
system; the SetPaths desk accessory mustbe used. WhentheDA 
starts, the search paths specified by shell variable are already 
listed in (һе DA’s dialog box. The user simply needs to select the 
"Set" button in the dialog to establish these search paths. The 
MPW script file is helpful because the version of the DA I have 
doesn't recognize Edit menu operations like Cut and Paste. A 
sometimes useful/sometimes troubling side effect of Set Paths is 
that most other applications which search the System Folder for 
help files or other support data will also search the Set Paths 
directories for those files. 


Example 3. Consulair' s Path Manager application. 

The Consulair method for specifying search paths is consid- 
erably more complicated, flexible and robust than TML's. There 
are many classes of files which may be sought in different 
directories. Consulair provides an application, Path Manager, 
which takes a user-written text file as input and writes a resource 
file containing search path information for the applications. The 
input source is alist of any number of search paths for the various 
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classes of target file. Consulair has not published the format of 
their path resource, so rather than using Rez, we will use MPW 
variables holding search paths for libraries and includes to 
augment a Path Manager input file. 

Many of the paths used with the Consulair applications are 
"source relative", meaning that the directories to be searched are 
specified by partial pathnames appended to the directory where 
thecurrent source file resides, rather than by full pathnames. This 
is a strong point in the design of the Consulair Path Manager 
strategy, and because many paths are source relative, many 
specifications in the Path Manager input will not change when 
the directory structure changes. The only paths we really need to 
worry about are the same ones considered in the MPW and TML 
systems: the locations of libraries and system include files. 
Therefore I prepare a template file for Path Manager input which 
contains the relative paths exactly as needed and which includes 
MPW variable references only for absolute pathnames to library 
objects and includes. When the paths change, I just need to 
change the values of the variables, expand the variables in the 
template file, and send this as input to the Path Manager applica- 
tion. 

Let's consider two sample lines in this template file which 
specify some directories to search for header files (included .h 
files) needed by the C compiler. Path Manager input lines look 
like: 


Outer-most scope Nested level 


Command file 
"FileB" 


4 VarA is undefined 
4 VarB is undefined 
4 VarC is "String Val" 


Set VarA "Redefined" 
Set VarB " local string" 
Set VarC "Changed" 


22. 


Set УагА "the String" 
4 VarB is undefined 
Set VarC "String Val" 
Export VarC 


P VarA | is "Redefined" 
# VarB is “оса! string” 
# VarC is "Changed" 


Figure 4. Shell variable scope 
anomaly associated with the 
launching of applications. Shell 
script FileB is implicitly closed. 
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“С Include *S *S:Includes: 

C Include (MacCLib)CIncludes: {MacCLib} Includes: 

The first item on each input line (“C_Include” in this 
example) indicates the class of sought object for the Path Man- 
ager and applications to use. A tab-separated list of directories 
to search follows the class identifier on each line. In the first line 
of the example, “ *$” is a Consulair metanotation which refers to 
the directory which contains the source file which is being 
compiled. This input line will cause the C compiler to look in the 
directory containing the source file and in a folder in that same 
directory which is named Includes. This input line is interpret- 
able “as is” by the Path Manager and does not need to be changed 
when different source directories are used. More information 
and examples of Path Manager input can be found in the Consu- 
lair documentation. 

The second line of the example fits our present purpose. It 
lists two directories which will contain system-wide include 
files. This line uses shell variable {MacCLib} to refer to the two 
directories as shown in Figure 3. But the Path Manager does not 
recognize the MPW shell variables, so we must expand the 
variable in this input line before passing the input file to the 
application. Shell script MakeCPath accomplishes this task, and 
launches the Path Manager. Note that the placement of the 
template file as shown in Figure 3 allows MakeCPath to use 
variable {MacCLib} to locate the template. If the template isn’t 
found we will know that the variable is not up to date! 

MakeCPath uses the template file as input and writes the text 
file which will be read by the Path Manager application. The file 
for the Path Manager is named MacC.Path and placed into the 
System Folder for later reference. Expanding the variables in the 
template file without altering any other text requires a little bit of 
mental contortion and the use of an intermediate scratch window. 
The first step in the process is to open a window to the template 
file. In the template window, we literalize any characters which 
might be mistaken for shell metacharacters. For example, the 
asterisks in the “*S” entries above must be literalized. The 
sequence of commands 

Find * 

Replace -c œ /d*/ 7999%! 

inserts three curly-d's in front of every asterisk in the 
template. The three adjacent curly-d’s cause literal interpretation 
of the asterisk through the next two shell commands which 
interpret the line. Note that in general, 2^-1 curly d's will 
literalize a character n times. Any other MPW shell special 
characters which appearin the template must be similarly quoted. 
MakeCPath only literalizes asterisks and tabs; add your own as 
needed. Note that the curly-d's are being added directly to the 
template window. When we are finished with the template, we 
must close this window with the -n option so the changes won't 
be written to the file on the disk. 

Once the template is prepared, loop to process it one line at 
atime. MacTutor masochists who read the code listings first may 
be mystified at the command 

Echo Echo 0” ‘Catenate 679” >> “{tmpfile2}” 

There may be a prettier way to doit, but this does work. This 
is an echo command which writes another echo command 
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as a line in the scratch window. The name of the scratch 
window is in the variable {tmpfile2}. The Catenate§ inside 
grave symbols is replaced in the scratch file by the line currently 
selected in the template file. This catenate command consumes 
one level of literalization in the template, so 990% in the template 
becomes 9% in the scratch file. Shell variables such as {Mac- 
CLib} are not expanded in the scratch file. 

When the loop finishes, the scratch file contains one echo 
command corresponding to each line of the original template file. 
Execute the commands in the scratch file using 


Execute “{tmpfile2}” >> “{outfile}” 


and the variable outfile contains the filename MacC.Path 
which will become the input to the Path Manager application. 
The echo commands in the scratch file consume one more level 
of literal quotes (so 9% becomes * in the output file) and they also 
expand any shell variables into their values. 

MakeCPath contains additional commands which facilitate 
convenient behavior after the application runs; these features 
will be considered in the next section. Finally the MakeCPath 
script launches the Path Manager, passing the file MacC.Path in 
the Finder Information structure. 

Now we run into some of the difficulties associated with 
applications in shell scripts. Although I passed the input with the 
Finder Info, the Path Manager (ver. 5 at least) doesn’t notice it. 
I still have to manually select a menu option, and then locate the 
text file using a StandardGetFile dialog. The best Ican do is make 
this process as painless as possible. In the MakeCPath script, just 
prior to launching the application, make the System Folder into 
the default directory using the Directory command. Now when 
the Path Manager throws up the StandardFile dialog, it will 
initially be showing the files in the System Folder. Since 
MakeCPath wrote the file MacC.Path into the System Folder, we 
won't have to search through the directory hierarchy to find it. 
When the Path Manager generates the PATH resources, I will 
also have to manually specify the output file in a StandardPutFile 
dialog, and then manually select Quit from the menus. We've 
saved ourselves some work in editing the input file, but if the 
application just used the Finder Information all the manual 
interaction could be eliminated. 


Altered states 

Now let's consider the things which happen in the shell 
environment when we launch an application. In the absence of 
Switcher-like trickery, we must terminate any current applica- 
tion prior to launching another one. The MPW Shell is itself an 
application and so must terminate before launching another and 
must be relaunched when the external application quits. In the 
parlance of the MPW Reference, MPW is "suspended", the 
external application runs, and then MPW is "resumed". The 
processes necessary to suspend and resume the MPW shell are 
performed by shell scripts provided with the MPW system, 
named (appropriately) Suspend and Resume. 

The Suspend script saves all currently defined shell vari- 
ables, exported variables, command aliases, menu items, the 
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current working directory, and апу open windows. Then when 
the MPW shell is relaunched, the Resume script uses this saved 
information to return the shell to nearly the same condition as 
when it was suspended. There is one important difference 
between the suspended state and the resumed state, which is 
tersely documented in the MPW Reference. An application may 
be launched from a nested command script, such as MakeCPath 
from the preceeding example, but the shell always resumes at the 
outermost command level. The shell implicitly exits any nested 
command scripts when suspended. 

This is the variable scope anomaly I to which I earlier 
alluded. The Suspend script saves the names and values of 
variables at the current level of scope, but the Resume script sets 
these variables again at the outermost level (see Fig. 4). WARN- 
ING: Iusethisas a “feature”, but future versions of the shell may 
consider this a "bug"; some of my shell scripts will require minor 
modification if future releases change this behavior (I am using 
MPW version 1.0 for the examples of this article). [Current 
version is 2.0b1. -Ed] 

If you launch applications within scripts, as I do, some 
defensive scripting practices are essential. Any outer-level shell 
variables you want around after Resume must be exported from 
theouterleveland not modified by nested shells. Any inner-level 
variables you don't want around after Resume must be Unex- 
ported and Unset in the script file prior to the command which 
starts the application. Remember that you only need to worry 
aboutthis when youareusing shell scripts like MakeCPath which 
launch applications. 

Often, launching an application is not the final step in the 
process, but the shell script which launches the application is not 
restarted from that point. I get around this by setting up com- 
mands to be executed by the Resume process. I put these 
commands into a file and save the name of this file in a shell 
variable called (PostApp). I have modified the Resume script 
file to include the commands: 

Execute “{PostApp}” 

Set PostApp NullFile 

When the MPW shell resumes after an application, com- 
mands which I saved prior to suspending can be executed. 
Variable (PostApp) is reset to a default empty command file 
which is named "NullFile". An alternate method that doesn’t 
depend on the Suspend/Resume shell variable scope anomaly is 
to save the commands under a specific file name, say “ОѕегВе- 
sume”. Then the Resume script should contain 

Execute "UserResume" 

Echo ""» UserResume #Deletes contents 

I prefer the first method (as long as it works) because the 
command file contents stay available for debugging when I am 
writing a new command script. Note that in either method the 
changes to file Resume are permanant, and we merely change 
variable {PostApp} or file UserResume to fit the needs of the 
moment. 

I return to the MakeCPath script for an example of a useful 
Resume task. Recall that MakeCPath changed the current 
working directory to the System Folder just prior to launching the 
Path Manager. This means that the Suspend script will save this 
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directory and Resume will restore the System Folder as the 
current working directory. This will probably not be the direc- 
tory from which the user started the MakeCPath script, so when 
we Resume, we are not where the user expects. А more 
user-friendly thing to do is to save the original working directory 
and restore it at the end of the Resume process. The commands 
which set this up are found near the beginning of MakeCPath. 
Variable (PostApp) is given the name of the resume command 
file "UserResume". The original directory is used in acommand 
stored in file UserResume: 

Directory "OldDirectoryName “ 

Now when MPW resumes, the user will be in the same place 
in the directory hierarchy as when MakeCPath was invoked. This 
technique of adding transient commands when resuming from 
applications has considerable utility and we will see more exten- 
sive examples presently. 


MPW Make with Applications 

The shell scripts developed in the preceding text, while they 
do provide instructive examples of technique, are only moder- 
ately useful. The directory structure and library file locations 
shouldn't change too often, and these shell scripts are unlikely to 
be needed more than a couple of times a year. 

Building and maintaining programs, on the other hand, is 
more of a daily occupation. Within the MPW, these tasks center 
around the tool “Маке”, which is an elegant system of rules to 
emit commands which depend upon the relative ages of files. If 
we apply what we learned in the previous examples to this 
problem, we are rewarded by a system of genuine utility — an 
integration of MacC and TML Pascal systems which the devel- 
oper accesses from entirely within the MPW environment. 


Basics of Make 

"Make" programs are widely available utilities found in the 
MPW, in a variety of Mac shareware and commercial offerings 
and in most Unix— based systems, among others. The traditional 
use of a Make utility is to keep programs up to date with a 
minimum of processing, compiling only when source files 
change and linking only when relocatable objects change. This 
behavior is controlled by a text file containing 1)dependency 
rules specifying which files are constructed from which prede- 
cessor files and 2)а list of commands which perform the 
operations necessary to update the target files. SinceF. Alviani's 
April '87 MacTutor article elaborated some of the sketchy 
documentation on Make, I won't repeat that detail here. An 
important point in the adaptation of MPW Make for applica- 
tion—based development is that the full range of legal com- 
mands can be generated by a make script. This allows us to 
generate “smart” sequences of commands which do much more 
than just compile and link (and Rez"). 

The MakeCPath command described earlier provides the 
simplest possible illustration of Make which does not compile or 
link. The final output of MakeCPath is a resource file in the 
System Folder named Paths.Rsrc. Thisoutput depends, naturally 
enough, on the input — the template file, C.Path.Template, and 
any shell variables , such as (MacCLib), which are used in the 
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template file. Dependencies іп Make can only be specified with 
respect to files, not variables, so the values of (MacCLib) and 
related variables are initialized in the MPW script file "Startup". 
"Startup" is a script supplied by the MPW system which is 
executed when the MP W shell is launched from the Finder. If I 
change the value of variable (MacCLib) by editing this script 
file, the dependency of Paths.Rsrc on the variable becomes 
equivalent to a dependency on file "Startup". (1 put these 
variables into “Startup” instead of UserStartup" because I edit 
file "Startup" much less frequently). 

The input to Make specifies these dependencies in a special 
notation: 

Paths.Rsrc 

MakeCPath 

The line containing the f symbol is the dependency state- 
ment. Files listed to the left of the f depend upon (or are made 
from) files listed to the right of the symbol. Dependent files (left 
side) need to be updated if they are older than any of the 
predecessor files (right side). Note that in an actual Make script, 
you might need to specify the appropriate directories as well; I 
have omitted this detail for the clarity of the example. The 
dependency statement may be followed by a list of commands 
which perform the necessary update. Commands are distin- 
guished in the Make input because each line of a command list 
begins with whitespace (space or tab characters). In the example 
above, *MakeCPath" is the command which will update the 
target, “Paths.Rsrc”. 


f Startup C.Path.Template 


Example 4. The MixMake command 

Here I develop a shell script and Make input which work 
together to build programs. To effectively use applications with 
shell scripts, we need an understanding of their behavior in this 
environment. I start this example, therefore, by cataloging what 
happens to each application when it is launched from the MPW 
shell with an appropriate input file specified in the Finder 
Information structure. MacC (ver. 5) does notuse the Finder Info 
properly, and in fact gives an ID 02 bomb (or worse) when you 
try from the shell. The Consulair linker will process a link script, 
but when finished puts up a standard file dialog, and requires user 
interaction to quit to the shell. If the link fails, the Consulair 
linker will launch Edit, instead of the shell, if it can find it. 
Removing the Edit application completely from the disk is 
helpful in using the MixMake shell script. TML Pascal will 
compileone file from the FinderInfo (even if several were listed). 
After compiling, it requires the user to click OK buttons, to select 
other files or to quit manually. The TML linker will use a link 
script passed in the Finder Info, and then runs the program it built 
and/orreturns to the shell. Amazingly, the Microsoft FORTRAN 
compiler (ugh) has almost ideal performance in this environ- 
ment; it compiles the file passed in the Finder Info and returns to 
the MPW shell, and only requires the user click an OK button if 
a compile fails. 

So far, things are looking a bit dim, but utility applications 
can save the day. The Exec application, provided with the 
Consulair system, is a simple utility which runs Consulair appli- 
cations in sequence according to an input text file. Like the Path 
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Manager, when this is launched from the shell the user must 
select the input file manually, but it generally will return to the 
shell when done. Furthermore, the Consulair linker and compiler 
recognize that they have been launched by Exec instead of the 
shell, and they accept and process input files and return to the 
Exec without user intervention. The MPW method simply needs 
to use this launching indirection through Exec to perform an 
automated build. The TML applications unfortunately do not 
change their behavior for Exec. Many other free/cheap utilities 
(for example, Darin Adler's Sequencer) will run applications 
with input files in sequence and may be more appropriate for the 
non-Consulair applications. 

The MixMake command, which builds programs with 
MacC and TML involves a significant amount of programming 
beyond the simple Make utility. Since Make will, however, form 
the heartof the MixMake command, let's consider first the nature 
of a MixMake makefile. When the dependency rules indicate 
that a source must be recompiled or a program relinked, a 
MixMake makefile generates a line of input for the Exec appli- 
cation instead of a command to run the compiler or linker 
directly. 

Asample makefile for an applicationis given in the Listings. 
The default dependency rules, which are applied to any filename 
with the appropriate filename extension, effectively handle all 
the compile steps. These default dependency rules may require 
directory dependency rules as well to operate correctly, but this 
will tend to vary with each build target. The default compiling 
rules are: 

Rel f .C 

Delete -i (TargDir)(Default).Rel 
Echo (DepDir)(Default).C »»(Cfile) 
Set RunMacC 1 
.Rel f .Азп 
Delete -i (TargDir)(Default).Rel 
Echo (DepDir)(Default).Asm >>{Cfile} 
Set RunMacC 1 
.Rel f .Раз 
Delete -i (TargDir)(Default).Rel 
Echo ‘Pascal  (DepDir)(Default).Pas Exec' à 


»»(Efile) 
Set RunTPas 1 
.Взгс f „В 


Delete -i (TargDir)(Default).Rsrc 

Rez {RezOpt} -o {TargDir}{Default}.Rsre д 

(DepDir)(Default).R 

Variable (Efile) is the file which is being prepared for Exec 

input. Variable (Cfile) is a filename with extension ".Files" 
which contains a list of sources to be compiled by the MacC 
application. Setting the variable (RunMacC) tells the enclosing 
MixMake shell command to add a single command to the Exec 
input file which will launch the MacC compiler with the "Files" 
file. If resources are to be compiled with Rez, the commands are 
generated by Make and executed directly by the MixMake script. 
This arrangement assumes that non-CODE resources are com- 
piled by Rez but the application is assembled from CODE and 
these resources by a subsequent link step. When a Pascal source 
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is to be compiled, the makefile appends an appropriate command 
to the Exec input file. Since the Pascal compiler does not 
interface well with Exec, the user must select (and know in the 
first place) all the sources to be compiled in Standard File dialogs. 
When the user selects Quit from Pascal, the Exec processing is 
terminated and MPW resumes. To complete any MacC compil- 
ing and linking, the user would have to run the MixMake 
command a second time. 

A much nicer method uses Adler’s Sequencer and could be 
adapted most to any application-running utility; a Pascal com- 
piler build rule is implemented as Rez input which is used to 
produce a Sequencer which will build the desired Pascal files. 
The user does not need to know which Pascal sources are to be 
rebuilt; the user just selects Quit in Pascal’s file menu after each 
compile, and the next out-of-date file is compiled automatically. 
The final operation by the Sequencer after all Pascal files are 
compiled is to launch the Exec to handle C compiling and 
Linking. I have included both versions of MixMake with the 
source code, but will not describe this one further in the text. The 
extra effort to use the Sequencer (or similar utility) has signifi- 
cant benefit. The Suspend/Resume scripts take a noticeable time 
to execute, so we want to do as much work as possible outside the 
shell for each Suspend/Resume cycle. 

The sample Makefile.Template in the listings illustrates the 
appropriate specifications needed to build a particular file. It 
adds a directory dependency rule before the default compiler 
rules. A dependency rule for the link step must explicitly list the 
link script (“І іпк” file), relocatable object files (“.Ве!” files) and 
compiled resources (“.Көгс” files) which are needed. The com- 
mand generated by this dependency rule is again an appropriate 
line of Exec input. Particular care must be taken to prevent 
building a program with some up-to-date object files and some 
which are not up-to-date because of compiler errors. The delete 
command in the compiler default rules described above is exe- 
cuted by the MixMake script and prevents a successful link until 
the object is successfully rebuilt by the compiler. The MacC 
compiler rules don’t need to delete obsolete objects because the 
Exec-MacC system allows a time saving alternative. Each line 
of Exec input consists of four fields: 1)the application to launch, 
2)the input file for the application to process, 3)an application to 
run if the application in field 1 runs successfully (normally Exec 
to continue processing), and 4)an application to run if the 
application in field 1 fails. The line of Exec input which 
MixMake uses is 

С input.Files Exec Done 

The application “Done” is a trivial program containing only 
an ExitToShell command. If any of the files to be compiled or 
assembled by MacC have errors, the Exec processing terminates 
before any attempt to link, and the Done program Resumes the 
MPW shell instead. 

It is important not to list the MPW Shell directly as an 
application in the Exec input The MPW shell could be 
launchedby Exec, but then selecting Quit from the MPW File 
menu resumesthe MPW shell instead of starting the Finder. This 
is quite confusing, so we don't do it. 

There are few restrictions on MixMake. The MixMake 
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command shell takes user input arguments exactly like Make, 
and uses a makefile with the appropriate default rules described 
above to generate an input file (set up to run in the appropriate 
order) for the Exec application. The Make tool’s options —4, -е, 
-f can be used in arguments for MixMake. Make options -p, -г, 
—S,—t,—u should not be passed to MixMake; they may not behave 
as expected. Options —r, -s and —u can be used by invoking Make 
instead of MixMake and using the MixMake input dependency 
file. The key to adapting the sample makescript to a particular 
purpose is in the list of predecessors (usually for a link rule) and 
directory dependency rules. It is important to follow the advice 
in the MPW Reference and assure that directories are specified 
in default directory dependency rules in precisely the same form 
(full or partial pathnames) as the corresponding explicit prede- 
cessor files. These should also be consistent with the search paths 
of the applications. The version of MixMake which uses the 
Sequencer requires that full paths are specified for all directories. 

In the simplest implementation, MixMake would simply 
launch the Exec or another application runner. А more sophis- 
ticated MixMake, however, provides Resume tasks for "nice" 
error handling when the build steps don't succeed. ГИ finish up 
the article with a description of commands which help with 
analyzing diagnostics. 


OOPS! What about those errors? 

All of the Consulair and TML applications write diagnostic 
files when compiling or linking fails. A convenient feature to add 
to the mixed system is a facility to automatically open a bad 
source listing its corresponding diagnostic file simultaneously. 
Shell script “CompErr” is just such a “diagnostic viewer", 
running sequentially through all bad .C and .Asm sources, then 
all bad .Pas sources, and finally any failed linker scripts. The 
information needed by CompErr to tell which are the “Бай” 
Sources from the most recent build attempt consists of several 
files and shell variables. These files and variables are provided 
by a Resume script which is installed by the MixMake command. 
А copy of the commands MixMake generates as a Resume task 
is kept in file "MixMakeResume". These Resume tasks and the 
CompErr command are more limited than MixMake itself, and 
generally work only when all the necessary sources and diagnos- 
tics are located in a single directory and if that directory is the 
current working directory when the MixMake command is 
invoked. This restriction has not been onerous for me, but if 
necessary more elaborate Resume and CompErr scripts could 
circumvent the limitation. 

The MixMake Resume commands write files which contain 
lists of paired source and diagnostic files. The Resume com- 
mands also install an *Open Diagnostics" item in the MPW shell 
File menu that runs the “CompErr” command. The files summa- 
rizing the diagnostic file names are scanned sequentially by 
"CompEzrr"; each time the menu item is selected, the next pair of 
Source and diagnostic files is opened for the user to view and edit. 
When all the diagnostic files have been opened, the menu item 
deletes itself. 

The MacC compiler creates a file with the basename of its 
Files input and the name extension .Fer, in which it writes а list 
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of files which failed to compile and their corresponding diagnos- 
tic files. For Pascal compiler and linker errors, the Resume task 
needs to explicitly search the directory to create such a list. For 
example, in a directory containing a Pascal source with extension 
Pas, the existence of the same name with extension .Per suggests 
a failed compilation. Existence of the diagnostic file is not 
sufficient evidence however; the source might have been cor- 
rected since the diagnostic file was created. The Resume task 
only lists source files which are out-of-date with respect to their 
corresponding diagnostic files. The Make tool, a real workhorse, 
assures this. Here are dependency rules for finding bad sources 
from diagnostic files: 
‚Раз f .Регг 
Echo (DepDir)(Default).Pas д 
{DepDir} {Default}.Per >>TMLP.Fer 
.Link f .Lerr 
Echo (DepDir)(Default).Link д 
{DepDir} {Default}.Lerr >>TMLP.Fer 

All the Pascal diagnostics are listed in a file named 
TMLP Fer and all the link diagnostics in a file named Link.Fer. 
The dependency rules above are in a makefile permanantly stored 
(never accessed by the user). This has the advantage of allowing 
a general command to be built around it, but the disadvantage that 
it will only work within the current directory. 

CompErr uses these files (from the most recent MixMake 
build only), opening one source/diagnostic pair for each invoca- 
tion. CompErr should always be accessed through the "Open 
Diagnostics..." menu item (“Dial Ста-Е for Errors") because 
the menu procedure moves to the directory where the build 
occurred, opens the files, then returns the user to the current 
. directory. Since CompErr works sequentially through the .Fer 
files, we need to save the current position in the files after each 
invocation. Counting line numbers might work, but I have 
chosen to use the method of saving the current window selection 
with the file. 

In MPW, files and windows into those files are distinct, 
although intimately related. When we save a window, the 
selection is saved too. After the window is closed, the saved 
selection reappears when the window is opened. The Save 
command is pretty smart, and only writes changes to the disk 
when the text has changed, not when only the selection changes. 
The CompErr script forces saving new selections by writing 
innocuous white space into the .Fer file after each change of 
selection. The marker for where CompErr is in the file is 
therefore saved elegantly in the file itself. 

OK, let's finish up with an ugly scenario. It is Friday 
afternoon, you are about to leave on vacation and a lengthy build 
has just resulted in 30 or 40 erroneous source files. You don't 
particularly want to re-Make the whole shebang just to prime 
CompErr when you return. NO PROBLEM! If we can have 
Suspend/Resume tasks, we can also have Quit/Startup tasks. 

Two scripts delivered with the MPW system, appropriately 
enough named “Quit” and Startup, handle special tasks when the 
user elects to terminate the MPW shell by quitting to the Finder 
and when the shell is launched from the Finder. I have added 
routines to Quit and Startup which allow me to preserve any state 
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variables I want between invocations of the shell. In the Quit 
script, I execute a command file named "QuitPermVars". In 
QuitPermVars are commands which save two exported state 
variables required by CompErr: (MakeErr) and (CompErrDir). 
QuitPermVars writes Set commands to reproduce these two 
variables, corresponding Export commands, and an AddMenu 
command to install the “Open Diagnostics" item. These com- 
mands are saved in a file named "StartPermVars". Then the 
Startup script executes StartPermVars when the shell is launched 
from the Finder. So you can leave your problems behind, and 
when you come back with clear and refreshed mind, CompErr 
will dutifully pitch them out to be solved. 


Conclusions 

Although it may look a bit ungainly because of the number 
of small command files, the system I have presented here as an 
example is quite workable and I actually use it every day. 
Programming the shell is very challenging compared to other 
programming because of the global nature of many of the 
manipulated data and the resulting high data connectivity of 
"independent" modules. But the rewards of mastering shell 
programming can be great. Before I attempted this project, in a 
fit of frustration, I had presumed it would be impossible to 
integrate these diverse applications with the shell. The flexibility 
of the MPW should not be underestimated however, and this 
collection of command scripts provides me with the same level 
of performance from the development applications as when they 
stand alone plus an improved text handling and resource han- 
dling facility. 

I should add that the systems integration designed into the 
Consulair C applications contributes a greatly to the effective- 
ness of my scheme. The behavior of the various applications 
(Consulair's, TML’s and others!’ ve tried) could have been better 
for use from the shell however. A few simple considerations can 
insure smooth integration of applications and MPW shell. 

Making applications MPW friendly 

First and foremost, applications which may be launched 
from the MPW shell (or other non-Finder shells, like A-UX?) 
should handle the Finder Information structure. No assumptions 
should be based on Finder behavior (for example, assuming that 
documents and application must reside in the same folder when 
they have different file creator words). 

Secondly, applications with strongly modal behavior should 
probably have the ability to read an input file to set those modes 
and perform its action. An application which can do its job with 
just one or two mouse clicks by the user in menus or dialog boxes 
has strongly modal behavior, and compilers are an excellent 
example. There is unfortunately no way to establish a standard, 
but the following suggestion should provide a sufficiently con- 
venient interface with the MPW shell. If you have a strongly 
modal application, consider using a TEXT file, perhaps with a 
distinctive name or filename extension, as an optional way to set 
the modes and actions to be performed. And finally, when an 
application can be controlled modally in this way, provide an 
option to Quit or Transfer without user intervention. Yes, [know 
this flies in the face of the User Interface Guidelines, but the 
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example of this article shows that the User Interface is not always 
the Best Interface. 


А challenge to future MacTutor authors 

The MPW system provides a Help tool which provides on- 
line documentation for shell commands. In the listings for this 
article I have included a script named Man (for Manual) which 
extends the help procedure to search both the default help file and 
a second help file named Local.Help. The Man procedure also 
uses the Canonical spelling tool to convert your standard com- 
mand aliases to the command names known to the system. Just 
put an alias and corresponding command on a line in file 
Alias.Dict. 

With the Man command, I have provided a Local.help file 
with entries for the command scripts developed in this article. 
Hopefully the command scripts and tools in future MacTutor 
articles can include relevant help file entries with their source 
code contributions. 


Listings 
янв file ReadMe 
пип ReadMe - instructions for installing 
#88 MixMeke and related commands in your 
eum MPW system. 
#88 W.G. Powell 1987 
uum Because parts of the MPW system will usually 
"um be scattered throughout а number of HFS 
nun folders (directories) the following guide 
888 will be helpful in adding the sources 
"t provided here. You may need to customize file 
ан paths in some of the commands to match your 
нин directory arrangement. 
num Into the MPW directory Cthe folder containing 
RRR the MPW Shell application itself, and referred 
чин to by shell variable (MPW), place the f iles 
888 contained in the source disk folder "for MPW folder” 
ung Local.Help 
ttt QuitPermVars 
uu StertPermVars 
инн :MekeSupport: the folder апа its contents: 
RRR MekePErrs .mk 
BRR Mixmake. Template. 1 
RRR Mixmake. Тепр1а{е.2 
иип MixMakeResume 
"nm Paths . mk 
eun Into the Tools directory Cor any directory listed 
nun in the MPW command search path (Shell variable 
иин (Commands) ), place the files contained 
"uu in the source disk folder “for Tools folder” 
ttt Alias.Dict 
ашп СотрЕгг 
nun MakeCPath 
num MakePPath 
RR Man 
unu ‘MixMake мег. 1’ 
"um ‘MixMake уег.2” 
"ut NullFile 
nun UpdatePaths 
nuum If you use Darin Adler’s Sequencer with MixMake, 
nun rename version 2 “МіхМаке“. 
eun If you use Consulair/MDS Exec only with MixMake, 
888 rename version 1 "МіхМәке”. 
шш Use the appropriate template in directory 
нин (MPW)MekeSupport: as а guide in preparing 
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ия your own MixMeke makefiles. 

"n Into the Applications directory Cor апу directory 
Ree listed in the MPW command search path 

ttt (Shell variable (Commands) ), place the applications 
888 you will be using with the system. 

нип Consulair applications: 

"ut C 

"um Exec 

nun Link 

888 ‘Path Manager ’ 

иип ТМ. applications: 

"eut Pascal 

"it ‘TML Link’ 

nng Other applications 

sum _ Sequencer *if used 

RRR Done # supplied with this disk 

nan Note that if both TML and Consulair 

Ree Linkers are present, one must be 

uum renamed. 

eiit Also, since TML Desk Acc. "Set Paths" 

"um is rerely used, I install it in the 

Ree MPW Shell application, instead of a 

Rae precious System File slot. 

ипи The following changes should be made to the 


eut scripts supplied with the MPW shel] 


ЯНИЕ НН ТҮТТҮ ТТТ ДЫ. 


wae Add these commands to file Startup 
чин Modify to match your directory hiererchy. 


я — (PostApp) - name of command to execute when 

" MPW is RESUMED, after running а Finder application (WGP) 
Set PostApp "NullFile^ 
Export PostApp 


8 — (MacCLib)is directory for MacC includes and Libs 
Set MacCLib (Libreries)MacC: 
Export MacCLib 


8 — (TM.PesLib) is directory for TML Pascal interfaces, libs 
Set TMLPasLib *(Libreries) TMLPas:Pascal System TML:” 
Export TMLPasL ib 


8 — (TMPesInc) - Directories to search for 

8 TML Pascal interface files 
Set TMLPasInc "(Libraries)TMLPas:"^ 
Export TMLPasInc 


ЯНИЕ I E E HEEL UE EE 


иий Add these commands to file UserStartup 
"uu Modify to match your directory hierarchy. 


8 Recover values of saved state variables 
Execute "(MPW)StartPermVars"^ 


nuum mimm HH OU HE 


888 Add these commands to file Quit 

"um Modify to match your directory hierarchy. 
#88 Values of variables below are saved 

abi between invocations of the shell 


Execute *(MPW)QuitPermVars"^ 


uniti t HH EE HH HH HE HEU HEEL НИНЫ 


ttt Add these commands to the end of file Resume 
"un Modify to match your directory hierarchy. 


System for nice return from applications 

The shell variable "PostApp^ contains а command to 
Execute when resuming. This variable is reset to a 
default so unexpected results are avoided when another 
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* application is run. 
Execute * (PostApp)^ 
Set PostApp "NullFile"^ 


иш File MakePPath 

# Try using Rez to write path info to the TML path file 

# in the system folder. Basically, just need to expand the 
8 TMLPasLib and TMLPasInc vers and write some Rez input 

# with it. 

з W.G. Powell 1987 Гог MacTutor 


8 Nonzero command status doesn’t mean errors, 

% so don't terminate 

Set —oldExit (Exit) 

Set Exit 0 

8 Open temporery windows 

Open -n -t Tmpf il 

Open -n -t TMLPethOut 

п Write Rez input using shell's TML path variables 
Echo *ttinclude à^Tgpes.rà^^ TMLPathOut 

в Create STR resource for single path іп (TMLPasLib) 
echo “resource à'STR д’ (128) à( 9» TMLPathOut 
echo *à"(TM.PasLib)à^^»» TMLPethOut 

echo *à);^» TMLPathOut 

# Put list of paths from (TM LPesInc) into a window 
echo (TMLPesInc) > Tmpfil 

* Break comma-separated list into individual paths 
Find O Tmpf il 

Set IDno 129 


оор 
If C(IDno) < 133) 
Find §a:a/,/ Tmpf il 
If C(Status) -- 0) 
echo “resource à'STR ð’ 2С (10по) д) a(^»»TMLPathOut 
echo *à^'Catenate Tmpf 11.8 `2**›› TMLPethOut 
echo *3); *›› TMLPathOut 
Set IDno ‘Evaluate C(IDno) + 1)° 
Find 84:84! 1 Tmpf i1 
Else 
Find §a:= Tmpf il 
If C(Status) == 0) 
echo “resource à'/STR 9” 9((10по}д) a(^»»TMLPathOut 
echo *à^'Catenate Tmpf i1.8^ à^^»» TMLPathOut 
echo 9); *›› TMLPathOut 
Set IDno ‘Evaluate ((IDno) + 107 


оор 
If ((IDno) < 133) 
Echo “resource à'STR ð’ 2С (10по) д) 9(9%9%9);%9 
>> TMLPathOut 
Set IDno ‘Evaluate C (IDno) + D’ 
Else 
Break 
End 
End 
Else 


oop 
If C(IDno) « 133) 
Echo "resource 9”5ТР ð’ dC (10по) д) 9(9”9%9);%9 
>> TMLPathOut 
Set IDno ‘Evaluate (С (IDno) + 1)“ 


Else 
Break 
End 
End 
End 
Break 
End 
Else 
Breek 
End 
End 
642 


# Use Rez to write the Paths file. 

* Close temporary windows. 

Close -n Tmpf il 

Rez -o "(SystemFolder)Paths File” -t ‘ZSYS’ -c ‘MACS’ д 
TMLPathOut 

Close -n TMLPathOut 

Set Exit (—oldExit} 

Unset —oldExit 

Exit 0 

ишинин CCC CCC CCCE EEE EECELELLLES 


нип File MakeCPath 

uut MakeCPath - MPW Shell Script 

888 Set up input for Consulair Path Manager 
888 using appropriate MPW shell variables. 
чин william G. Powell 1987 for MacTutor 


8 Save current working directory 
# ала return to it after Path Manager quits. 
Set PostApp 0””(MPW)“UserResumed” 
Echo Directory à^'Directory'à^» *(MPW)UserResume^ 
Echo "Delete -i MekePtOut^»» *(MPW)USerResume" 
Echo Unset outfile >> *(MPW)UserResume" 
8 Specify the input template file 
Set infile “(MacCLib}C.Path. Template” 
8 Place the output text file (input for Path Manager) 
я into the system folder where easily found 
Set outf ile *(SystemFolder)MacC .Path^ 
8 Assign temporary file to window and clear it. 
Set tmpfile2 "(MPW)tmpf ile2^ 
Open -t -n “(ітрГі1е2)” 
Clear 0:» "(ітрГі1е2)” 
8 Open the template window 
Set _oldExit (Exit) 
Set Exit 0 
Open -t *(infile)^ >> Dev:Nu11 
If (Status) != 0 
Alert “Cannot Find/Open the input template file.dnd 
Check shell variable MacCLib, current lydn (MacCL ib)” 
Close -n "(tmpfile2)" 
Set PostApp "NullFile^* Reset default Resume tasks 
Exit 2 
End 
Set Exit (_oldExit) 
Unset .oldExit 
8 Add necessary quote characters to the template file. 
Find 0 | | 
Ёер1асе -с = / / "дд * 8 tab characters 
Find 0 
Replace -c = /d*/ “099%” 
# Loop to copy each line of input, 
8 expanding variables where necessary. 
Set loopend ‘count -1 *(infile)^' 
Set Тоорслі 1 
Loop 
If (loopcnt) > (loopend) 
break 
End 
Find (loopcnt) 8 Select next line of input 
8 Write command into temporary window which will 
8 expand shell variable paths when writing to (outfile) 
Echo Echo à^"'Catenate 879%» "(tmpfile2)" 
Set loopcnt ‘Evaluate С (loopcnt) + 1 ) 4 increment 
End 
8 Don’t terminate script file on errors below - the possible 
8 errors ere not importent enough! 
Set _oldExit (Exit) 
Set Exit 0 
* Open, clear, and write the output file 
Open -t -n "(outf ile)” 
Clear 0:9 “(outfile}” 
Execute “(ітрГі1е2)” >> ”(outfile)” 
8 Close 811 working windows, saving only the output. 
"Close -n "(ітрГі1е2)” 
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Close -n “(infile}” 

Close -y "*(outf ile)” 

# Remove all unneeded variables. 

Unset infile 

Unset tmpfile2 

Unset loopend 

Unset loopcnt 

8 Change "exit on error" flag back to original value 
Set Exit (-oldExit) 

Unset -oldExit 


® Change default directory to System Folder 
Directory *(SystemFolder}” 

* Execute the Path Manager, passing our new file 
8 in the Finder Information structure. 

“Path Manager” *{outf ile)” 


Exit @ * Control should never reach this statement 
НАНЕНННННННННННННННИНИНИНИНННННИННННЕЕВВЕ 


#88 File Pathe.ak 
* Makefile to ensure that Consuleir and TML search paths are 
# up to date with appropriate shell variables 


в W. Powe111987 for MacTutor 


8 Variables containing search paths for library files and 
8 include files ere defined in the Startup script so we 
8 want to rebuild when the Startup file is changed. 


яяя TML Pascal Paths File 
* (SystemFolder)Paeths File” f 
MakePPath 


* (MPW)Startup^ 


888 Consuleir MacC Path.Rsrc File 
*(SystemFolder)Peths.Rsrc^ f  “(MPW)Startup” à 
“(MacCLib}C.Path. Template” 


MakeCPath 
810180051 0090009009800 00 09 8 ннн a eB a HH HUE EE eas НН 


"um File MixMake ver.1 

#88 MixMeke version 1. 

988 Uses only Consulair Exec application runner 
#88 Script file to build programs with 

#88 MacC ог TML systems 

"um W.G. Powell 1987 for MacTutor 


#88 Initialize variables 

8 Ехес and MacC input and scratch files 
Set Efile *"Exec.Job"^ 

Set Cfile "MacC.Files"^ 

Set Lfile "Link.Tmp^ 

Delete -i *(Efile)^ *(Cfile)^ *(Lfile)^ 
8 Application run flags 

Set RunMacC 9 

Set RunLink 8** Consulair 

Set RunTMLL ink 0 

8  Meke's working directory 

Set MekeWD *'Directory'^ 

Export Макемо 


888 Run the Make tool 
паке ("Parameters") > MekeOutApps > Dev:StdOut 


88" Construct the input for the Exec application 
Execute MakeQutApps 
Delete MakeOutApps 
If C(RunMacC) == 1) 
Echo “С (Cfile) ExecDone^»"^(Efile)^ 
End 
If C(RunLink) == 1 || (RunTM Link) == 1) 
Catenate "(Lf ile)^ »»^(Efile)^ 
Delete -i *(Lf ile)" 
End 
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Unset RunMacC 
Unset RunL ink 
Unset RunTMLL ink 
Unset Lf ile 
Unset Cfile 
Unset MakeWD 


888 Set up the Resume tasks for after the applications 

888 Primarily for error handling 

Set PostApp “ (MPN)UserResume" 

Echo “Unset Efile” »"(MPW)UserResume^ 

Catenate “ (MPW)MekeSupport:MixMaekeResume^ »»^(MPW)UserResume^ 


888 If Diagnostic menu item is still around from 
888 an earlier build cycle, delete it. 

Set —oldExit (Exit) 

Set Exit 0 

DeleteMenu File “Open Diagnostics." > Dev:Nu11 
Set Exit (LoldExit) 

Unset . oldExit 


#88 Run applications using Consulair’s Exec 
Exec “(Efile)” 
"9890919090 Ho HH HHH HH HOO £8 oe es 28 HH HUE HUN (0484 


"utu File MixMake ver.2 
utt MixMake version 2. 
"888 Uses Sequencer application and Consulair Exec 


#88 Script file to build progrems with 
888 MacC ог TML systems 
888 W.G. Powell 1987 for MacTutor 


#88 Initialize variables 

8 — Exec and MacC input and scratch files 

Set Efile “MixMake.Job” 

Set Cfile *MacC.Files" 

Set Lfile "CLink.Tmp^ 

Set Tfile "TLink.Tmp^ 

Set Seqfile “Sequencer .R” 

Delete -i “(Efile)” “(Cfile}” “(Lfile}” *(Tf ile)" 

Echo “#include д”Турез.гд””› * (Seaf ile)” 

Echo “include à"(MPW)Applications:Sequencerà^ 2”С00Е27 7) 
»>”(Seaf ile)” 

Echo "resource ‘STR#’ (128,0^MixMake Compile commandsd”) 

3(%>>”(Seqfile}” 

Echo -n *à( >>” (Seqf ile)” 

8 Application run flags 

Set RunMacC 0 

Set RunLink 0% Consulair 

Set RunTMLL ink 0 

Я  Make’s working directory 

Set MekeWD "'Directory'^ 

Export MakeWD 


888 Run the Маке tool 
make (“Parameters”) > MekeOutApps ?Dev:StdOut 


#88 Construct the input for the Exec application 
Execute MakeOutApps 
Delete MakeOutApps 
If C(RunMacC) == 1) 
Echo “С (Cfile) ExecDone^» "(Ef ile)^ 
End 
If C(RunLink) == 1) 
Catenate "(Lf ile)^ »»^(Efile)^ 
Delete -i *(Lfile)^ 
End 
If C(RunTMLLink) == 1) 
Catenate "(Tf ile)" »»"(Segfile)^ 
Delete -i *(Tfile)^ 
End 
If C(RunMacC) == 1 || (RunLink) == 1) 
Echo «д^ (Макен) (Ef 11e) à^; ^» ^ (Seqf ile)” 
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Echo *à^(MPW)Applications:Execó^; ^» ^(Seqf 11е)” 
End 
Open -t "(Segf ile)" 
Find = *(Segfile)^ 
Clear \;\ "(Segfile)^ 
Echo *ànà)ón3) ; ^» "(Seqf ile)” 
Close -y *(Seqf ile)" 
Rez -o "(MPW)Applications:PasRunner^ ”(Seqf ile)” 
If (Status) == @ 
Delete -i *(Segfile)" 
End 
Unset RunMacC 
Unset RunLink 
Unset RunTMLLink 
Unset Lfile 
Unset Cfile 
Unset Tfile 
Unset MakeWD 
Unset Seqfile 


##8 Set up the Resume tasks for after the applications 
#88 Primarily for error handling 

Set PostApp * (MPN)UserResume^ 

Echo “Unset Efile” »"(MPW)UserResume" 


Catenate ~ (МРИ) МакеЅиррогі :MixMakeResume” »»^(MPW)UserResume" 


eae If Diagnostic menu item is still around from 
888 ап earlier build cycle, delete it. 

Set —oldExit (Exit) 

Set Exit 0 

DeleteMenu File “Open Diagnostics." ›Оеу: №11 
Set Exit (_oldExit) 

Unset —019Ех1 4 


gs Run applications using the custom Sequencer 
* (MPW)Applications:PasRunner" 
Shae ts snes a tua oe enn 0 see oe soe a0 e900 e308 2 tas os 9 as a at at ea a 


nae File MixMake. Template. 1 

#88 MixMake. Template. 1 

#88 Sample makefile for version 1 MixMake Command 
"uum W.G. Powell 1987 Гог MacTutor 


B88 Make variable definitions 
RezOpt = *-t 'RSRC'" 


8s" Directory dependency rules go here 

8 This one specifies thet rels аге 

8 in sister directory to that of the sources 
: :Rels: 5 

* Can add others of form 

= (AltSrcDir):Rels: f (AltSrcDir) 


$8" Default dependency rules for compilers 
8 Defeult C compilation rule 
Relf с 
Delete -i (TargDir) (Default) .Rel 
Echo (DepDir) (Defeult).c >» *(Cfile)" 
Set RunMacC 1 
п Default assembly rule 
Rel f Asm 
Delete -i (TergDir) (Default) .Rel 
echo (DepDir) (Defeult).Asm >> “(СҒі1е)” 
Set RunMacC 1 
8 Default Pascal compilation rule 
Relf .Раѕ 
Delete -i (TergDir) (Default) .Rel 
echo “Pascal (DepDir)(Default).Pas Exec Ехес”д 
yy “(Efile)” 
8 Default resource compilation rule 
.Ёѕгс ; 
Delete -i (TargDir)(Default).Rsrc 
Rez (RezOpt) -o (TergDir)(Default).Rsrc 
(DepDir) (Def au1t) .R 
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888 Program-specific dependency rules go here 

#88 For а program, should explicitly list the 

пип link script C.Link file), all objects C.Rel files), 
8$" and all resource files C.RSRC) needed to build. 

* Sample dependency rule for Consulair linker 

# progi f progi.Link progl.Rel sub!.rel prog.Rsrc 

# Echo “Link progl.Link Exec Done^»"(Lfile)" 
Set RunLink 1 


Semple dependency rule for TML Linker 
prog2 f prog2.Link prog2.rel 11Ы.ге1 prog.RSRC 
Echo “TML Link prog2.Link Exec Done^»^(Lfile)" 
Set RunTMLLink 1 


t$ tt 3$ 3$ оп 


"iut itti HH HH UO 09 0199 05209 005 0009 000 HOO HO EHE EO OO 2.22 


nug File MixMake.Tenplate.2 

нян MixMake.Template.2 

888 Sample makefile for version 2 MixMake Command 
eu W.G. Powell 1987 for MacTutor 


#88 Make variable definitions 
Ве20рі = *-t 'RSRC'^ 


яия Directory dependency rules go here 

8 This one specifies that rels are 

# in sister directory to that of the sources 
:: Rels: 

8 Сап edd others of form 

8 (AltSrcDir):Rels: f (AltSrcDir) 


5" Default dependency rules for compilers 
® Default C compilation rule 
Relf c 
Delete -i (TargDir) (Default) .re1 
Echo (DepDir) (Default).c >> “{Cfile}” 
Set RunMacC 1 
# Default assembly rule 
Relf .Аөп 
Delete -i (TergDir) (Default) .Rel 
echo (DepDir) (Default}.Asm >» *(Cfile)" 
Set RunMacC 1 
8 Default Pascal compilation rule 
Relf „Раз 
Delete -i (TargDir) (Default) .Re1 
Echo *à"(DepDir) (Default) .Pasà^»»"(Seqf ile)" 
Echo *9^"(MPW)Applications:Pascal9^»»"(Seqf ile)" 
8 Defeult resource compilation rule 
.Rsrc .R 
Delete -i (TargDir) (Default) .Rsrc 
Rez (RezOpt) -o (TergDir) (Default).Rsrc д 
(DepDir) (Default) .R 


#88 Program-specific dependency rules go here 

#88 For а program, should explicitly list the 

RRS link script C.Link file), all objects C.Rel files), 

855" and all resource files C.RSRC) needed to build. 

8 Sample dependency rule for Consulair linker 

prog! f prog!.Link progi.Rel subl.rel prog.Rsrc 
Echo "Link progl.Link Exec Done^»"(Lfile)"^ 
Set RunLink 1 


Sample dependency rule for TML Linker 

prog2 f prog2.Link prog2.rel 11Ы.ге1 prog.RSRC 
Echo ð” (full directory)prog2.L inka^; *›› ”{$ед ile)" 
Echo *à*(MPW)Applications:TML Linkd’; ^» * (Ѕедѓі1е) * 
Set RunTMLLink 1 


zt 13$ 3132 + + 3$ №. 8 


ЯННННННННИННННННННННННННННИННИНЯННИНИНИНННННЯ 


num File Done.c 


11595151555: 00 050 HH HH HH HH HH HH LH UO HH HUE AN 
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uu" File Done.c 
/YKFX153X53XXXXXXXXFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ 
/* Done.c */ 
/* Bogus Application for Exec to use to */ 
/* Return to MPW shel] %/ 
/* Written for Consulair Масс */ 


[ЖЖЖЖЖЖЖЖЖЖЖ ЖЖ КАЖ ЖЖ ЖЖ ЕЖА ЖЖ | 


80ptions Е G H 
main C) 


void exit() ; 
exit (0); 


uniti HH HE HO HE LEE EU EHE HL 


gut File MixMakeResume 

# MakeResume - а command file to be executed when 
8 — resuming from applications such as MacC 

t W. PowellMau 1987 Гог MacTutor 


# Don't terminate command file on non-zero status 
Set —oldExit (Exit) 
Set Exit 2 
Set CompErrDir *‘Directory *” 
Export CompErrDir 
# Establish а menu item for error handling 
DeleteMenu File “Open Diagnostics." > Dev:Nul1 
AddMenu File “Open Diagnostics../E” ‘Set Exit Ø; д 
Export MakeErr ; Set . origDir "'Directory'^ ; д 
Directory (CompErrDir) ;9 
CompErr ;д 
Set MakeErr (Status) ; Directory (—origDir} ;д 
Unset —origDir’ 
8 (MakeErr) is a flag used by CompErr, the command 
8 file which opens compiler error files 
Set MakeErr 0 
Export MakeErr 
8 Create summary files listing all files containing 
8 current compiler or linker diagnostics 
echo '^» TMLP.Fer 
echo ''» Link.Fer 
Files #.Pas »Dev:Nul] >0еу:М№11 
If € (Status) == 0 ) 
For — fil In #.Pas 4” 
If C*( fil)^ |= е) 
Маке (_fil} -f *(MPW)^MekeSupport:MakePErrs .mk 
End 
End > MekeOutApps ??Dev:Null 
End 
Files s.Link »Dev:Null 2Dev:Null 
If € (Status) == 0 ) 
For —fil In #.Link 4” 


If СӨС fil)” |= е) 


Маке (Lf il) -f "(MPW)^"MakeSupport:MakePErrs . mk 


End 
End >> MakeOutApps ??Dev:Null 
End 
Unset . fil 


Files MekeOutApps »Dev:Nu11 2Dev:Null 
If € (Status) == Ø ) 

Execute MakeQutApps 

rm MakeOutApps 
End 
8 Move insertion point to front of each 
8 summary file window and save window 
8 with that selection 
Begin 

Open -t MACC.Fer 

Find О MACC.Fer 

Replace $ ' “ MACC.Fer 

Save MACC Fer 

Close MACC.Fer 
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End 


Open -t TMLP.Fer 

Find о TMLP.Fer 
Replace Š “ * TMLP.Fer 
Save TMLP.Fer 

Close TMLP.Fer 

Open -t Link.Fer 

Find O Link.Fer 
Replace Š ° ' Link.Fer 
Save Link.Fer 

Close Link.Fer 

?Dev :Nu11 


# Reset (Exit) variable to previous value 


Set 


Exit ( oldExit) 


Unset —oldExit 
nuntii HE DH EE CE EE EU UN 


"num 


File MekePErrs .mk 


8 Make file to create error summary files from 
® build cycles with TML Pascal and Consulair and TML Linkers 
® This makefile is used by MixMake command’s Resume tasks 


‚Раз $  .PErr 


Link f Err 


(see file MixMakeResume ) 
М. Powell 1987 Гог MacTutor 


These dependency rules ensure we get only 
source files which 
have NOT been changed since the error files 
were written. 
* for TML Pascal 
echo (DepDir) (Default) .Pasa (DepDir) (Default) .PErr д 
yy TMLP.Fer 
8 for Consulair and TML Link 
echo (DepDir)(Default).Linkà (DepDir)(Default).LErr à 
)Link.Fer 


SUES RES £8 ahs 8s Shas os eas 8 Bs oe 8 He Os Bs HEEL EHE HU HELLE HUE HUE 001 


"nuu 


яия 
RRR 
RAR 
"nuu 
uuu 
"nutu 
nuu 
nuu 
RRR 
RRR 


File CompErr 


Shell script to find and open error files 
generated by MixMake 
command, opening a different files in sequence 
on subsequent 
calls. “.Ғег” files should have been created by MixMake’s 
Resume tasks. This script MUST be run by the menu item 
provided by the Resume task to work properly. 

(Status) returned by this command on exit is the new 
value for global shell variable (макеЕгг}. 

W.G. Powell 1987 for MacTutor 


8 Some commands intentionally return nonzero status, so 


Set 


Set 
ttt 


don’t terminate this command file 
-oldExit (Exit) 
Exit 0 
Pert 1 
Process MacC error files 


Files MACC.Fer ›Оеу:№11 2Dev:Nul] 8 Don’t need output 
If C(Status) == Ø && (MekeErr) == 0 ) 


8 File MACC.Fer exists 


AND still processing Mac C errors. 
Open -t MACC.Fer 
Find /’Errors in File: ‘/a:a/’ С7/ MACC.Fer 
® Open bad source 
If C(Status) == 0) 
8 find directory of source file 
Set . tmpSrcDir “‘Catenate MACC.Fer.Š `” 
Open -t -n MACC. tmp. tmp »Dev:Nu11 
Echo -n “( tmpSrcDir) ^ MACC. tmp. tmp »Dev:Null 
Find е MACC. tmp. tmp >Dev:Null 
Clear \9:\л:= MACC. tmp. tmp >Dev:Null 
Find 0:е MACC.tmp.tmp ?Dev :№и11 
Set | tmpSrcDir ""Cetenate MACC. tmp. tmp. S ^ 2Dev:Null 
Close -n МАСС. tmp. tmp 
8 open the file 
Open "'Catenate MACC.Fer. S^ 
If C(Staetus) # Ø) 
Alert “Cannot open source file ‘Catenate MACC.Fer .§*” 
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End 
Find / (See ‘/a:a/’)’/ MACC.Fer * Open diagnostic file 
If C(Stetus) == 0) 
Open “‘Catenate MACC.Fer.S^ ^ »Dev:Nu1l 
If C(Status) # 0) 
8 try again in source directory 
Open *(. tmpSrcDir)"Catenate MACC.Fer.S^^ 
If C(Status) ғ Ø) 
Alert “Cannot open error file ‘Catenate MACC.Fer .S^ 


End 
Unset —tmpSrcDir 
End 
Else 
Alert “Don’t know corresponding error file” 
End 


Else * Open file MACC.Fer after processing all 
# the files it named 
Open MACC .Fer 
If C(Stetus) * 0) 
Alert “Cannot open error file МАСС.Ғег” 
End 
Alert “Finished last Consuleir C Error File.onTML Pascal Next” 
8 Save current selection 
Find бл MACC.Fer ?Dev:Null 
Replace $ 4 “ MACC.Fer 2Dev:Null 
Save MACC.Fer ?Dev:Null 
Close -y MACC.Fer »Dev:Null 
Exit ‘Evaluate (MakeErr} + 1' 
End 
8 Save current selection 
Find $4 MACC.Fer >0еу:№11 
Replace $ * * MACC.Fer ?Dev:Nu1l 
Save MACC.Fer >0еу :№11 
Close -y MACC.Fer ?Dev:Null 
Exit (МәкеЕгг) 
Else If C(MakeErr) -- 0) 
Set MakeErr ‘Evaluate (MekeErr) + 1' 
# Go on to Pascal files 
End 
"ut Part 2 
#88 Process TML Pascal Error files 
Files TMLP.Fer »»Dev:Null ›деу:№11 
If C(Status) == 0 && (MekeErr) == 1) 
Open -t TMLP.Fer 
Find /0/a:a/ò / TMLP.Fer 
If C(Status) == 0) 
Open “*Catenate TMLP.Fer .S^ ^ 
If C(Status) != 0) 
Alert “Cannot open source file ‘Catenate TMLP.Fer*” 
End 
Find /д /a:/e/ 
If ((Status} == 0) 
Open “`Catenate TMLP.Fer .§*” 
If C(Status) != 0) 
Alert “Cannot open error file ‘Catenate TMLP.Fer.§*” 
End 


8 Open bad source 


ТМР.Еег 


* Open diagnostic file 


Else 
Alert "No corresponding error file" 
End 
Else 
Alert "Finished lest TML Pascal Error File.ónLink diagns 
next.” 
8 Save current selection 
Find Фа TMLP.Fer ?Dev:Null 
Replace S “ “ TMLP.Fer ?Dev:Nu11 
Save TMLP.Fer ›Оеу:№11 
Close -y TMLP.Fer ?Dev:Null 
Exit ‘Evaluate (МакеЕгг) + 1 ' 
End 
# Save current selection 


Find S4 TMLP.Fer ?Dev:Null 
Replace $ “ ^ TMLP.Fer >Dev:Null 
Save TMLP.Fer >0еу:№11 
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Close -y TMLP.Fer ?Dev:Nu11 
Exit (MakeErr) 
Else If C(MekeErr) -- 1) 
Set MekeErr ‘Evaluate (MekeErr) + 1° 
8 бо on to linker errors 
End 
unu Pert 3 
#8% Process Linker Error files 
Files Link.Fer »»Dev:Null ?Dev:Null 
If C(Status) == Ø && (MekeErr) == 2) 
Open -t Link.Fer 
Find /0/a:4/0 / Link.Fer 
If C(Status) == 0) 
Open “‘Catenate Link.Fer.§*” 
If C(Status) != 0) 
Alert “Cannot open link script ‘Catenate TMLP.Fer *” 
End 
Find /9 /a:/*/ 
If C(Status) -- 0) 
Open "'Catenate Link.Fer.S ^ 
If C(Status) != 0) 
Alert “Cannot open error file `Catenate TMLP Fer. S^ 
End 
End 


* Open bad source 


Link.Fer 


* Open diagn files 


Else 
Alert “All error files have now been processed!” 
* Save current selection 
Find S4 Link.Fer ?Dev:Nul1 
Replace Š * * Link.Fer ?»Dev:Null 
Save Link.Fer »Dev:Null 
Close -y Link.Fer »Dev:Nu11 
DeleteMenu File “Open Diagnostics...” 
Exit ‘Evaluate (MekeErr) + 1 ° 
End 
Exit (MakeErr) 
Else If C(MakeErr) == 2) 
Alert “All error files have now been processed!" 
DeleteMenu File “Open Diagnostics...” 
Exit ‘Evaluate (MekeErr) + 1° 
End 


Exit (MakeErr) 
SOEs ones en ten en ae.en nes ents snes es snes on enn ex enn en enn ex ex oe exes es ence os snes et enn N 


иип File QuitPermVars 

8888 This shell script is run by the Quit script 
#888 to Save any shell variables which must be 
8888 preserved through a Quit ; 
8888 И.С. Powell 1987 for MacTutor 


"Clear the file 
Echo 4” > *(MPW)StartPermVers" 


8 Save CompErr (Diagnostic viewer) state variables 
Echo “# State vars for CompErr^ »»^(MPW)StartPermVars" 
Set MakeErr >> “(MPW)StartPermVars” 
Echo "Export MekeErr^ >» *(MPW)StartPermVers" 
Set CompErrDir »»^(MPW)StertPermVers" 
Echo "Export CompErrDir^ >» *(MPW)StartPermVers" 
If C(MekeErr) « 3) 
* Still some compiler errors to process? 
AddMenu File “Open Diagnostics." 9 
›› “(MPW)Star tPermVars’” 
End 


ВНИИ НН НН НН НН НН HH OH HR 00008 


иип File StartPermVars 

"initial defeult values Гог CompErr stete variebles 
Set MakeErr 3 

Export MakeErr 

Set CompErrDir ^*^ 


Export CompErrDir 
ваниннииняпиннининянининининиинниянинининяиннянинин 
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nun File Man 


RRR MPW command “man” for on-line help 

nng Written 1987 W.G. Powell 

eun for MacTutor 

иш Search more than one file sequentially Гог help text 
Set Exit 0 

Set Reval 0 


""" Get standard command names from alias dictionary 
8 need temporary f ile 
Set _dmfl_ dumrxfx_ 
8 — Unalias the input arguments 
Echo (Parameters) 7% 
Canon "(MPW)billTools:Alias.Dict^ > *( dmf1.)^ 
8 Set new input arguments 
Set HelpList “‘Catenate ( dmf1 )'^ 
Delete -n (_dmf1_} 
888 Look for each requested item individually 
For HelpItem In (HelpList) 
8 Look in defeult help file first 
Help (HelpItem) > Dev:Nu11 
Set Retval (Status) 
If C(Retval) == 2 || (Retval) == D 
* Look in local help file if not in default 
Help -f *(MPW)Local.Help^ (HelpItem) > Dev:Nu1l 
Set Retval (Status) 
End 
If C(Retval) != 0) 
8 Keep a list of items NOT found for diagnostic 
Set Reval (Retval) 
Set NotFnd "(NotFnd) (HelpItem)^ 
End 
End 
иш Send error message if items not found. 
If C(Reval) != 0) 
Echo “888 Help: Cannot find items: ^Dev:StdErr 
Echo "#88 (NotFnd) ^»Dev:StdErr 
End 
Unset NotFnd 
Unset _dmf1_ 
Unset HelpItem 
Unset HelpList 
Unset Retval 


Exit (Reval) 
нинннинииининавониннивиининининвинининяннииниинин 


нин File Local.Help 
Help files for locally developed commands 
W.G. Powell 1987 for MacTutor 


Local - MPW Local Custom Commands 
Get info on specific command by entering 
Man CommandName 


CompErr ® Open compiler diagnostics and erroneous 
"sources 
MacC 8 Consulair applications: compiler, linker, etc. 


MakeCPath® Use shell variables to create Consulair paths 
MakePPath® Use shell variables to make TML paths 

Man # "help" utility including local help files 
MixMake % MPW make with Mac С, TML systems 

NullFile 8 А “do nothing” command f ile 

TML 8 TML Pascal compiler and linker 

UpdatePaths 8 Update TML Pascal, Mac C search paths 


O The Definitive MacTutor, Vol. 4 


Man [CCommandNeme | Keyword) .. 1 
Abbreviated on-line manual entries for commands. This 
is ап elaborate version of MPW help, which searches 
several files for help info. 
UpdatePaths 
Create new search paths for Consulair and TML, but only 
1) If (MPW)Startup (which contains path variables) changes 
2) If (MacCLib)C.Path.Template (Path Manager input) changes 
SEE ALSO: MakePPath, MakeCPath 


MakePPath 
Create new “Paths File” for TML Pascal in system folder. 
Pathnames come from shell variables defined in Startup: 
(TM.PesLib) contains one directory for libraries 
(TM.PesInc) contains up to 4 directory pathnames 

separated by commas. 

User must select Set Paths DA 
and click “ОК” afterwards. 


MakeCPath 
Create new "Paths.Rsrc" for Consulair in system folder. 
Also writes equivalent Path Manager text input file in 
System folder es "MacC.Path^. Input text file uses 
(MacCLib)C.Path.Template as main form, with additional 
pathnemes from shell variables defined in Startup file: 
(MacCLib) contains one directory pathname for libraries. 
C.Path.Template names several paths relative to 
(MacCLib). 


MixMake [option..] target.. 
Build programs using MacC and TML compilers 
Options: 
-d neme[-value] # define variable name as value 
8 Соуеггіде definitions in makefile) 
-е 8 rebuild everything regerdless of dates 
-f makefile 8 read dependencies from makefile - 
8 (default “MakeFile”) 
Other stenderd Маке options are not supported. 
The following options 
are helpful using the standard Make tool with the 
MixMake input dependency file 


-r # write roots of dependency graph to output 
78  ? write structure of target dependencies to output 
-t % touch dates of targets and prerequisities 
-u 8 identify targets in makefile not reached in build 
ту  " write verbose explanations to diagnostics 


SEE ALSO: Make, CompErr 
CompErr 
CALWAYS access via item “Open Diagnostics.” in File menu) 
Opens MacC, TML Pascal, or Linker diagnostic 
and source files. Generally only will work following a 
build 
attempt using command “МіхМаке“. 
Opens only one pair of files on each invocation 
- must be called repeatly for each source. 


NullFile 
Contains no command text. Does nothing. 


———————— 
File Alies.Dict х 
File Terget Sol 
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News From the 


Ask Apple Technical Support 
by Max ApplZone 


Welcome to the Macintosh Developer Tech Support col- 
umn. We at Mac DTS will use this column each month to answer 
your questions, report on the events at Apple, and pass along new 
Mac programming information. This is your chance to raise 
issues and questions just because you're interested in program- 
ming the Mac; you don't have to be a certified developer working 
on the next Mac database. 

The Mac Developer Tech Support group at Apple is a part of 
Developer Services, the organization whose job it is to promote 
and support third part developers. Tech Support's job includes 
writing TechNotes, creating sample code, generally helping to 
improve the quality of your code, and answering programming 
questions via electronic mail (either MCI Mail or our own 
AppleLink). This column is part of an effort to make our services 
more visible and available to the right people (you). 

If you have a programming question ora topic that you'd like 
to see addressed in this column, send a note (letter, postcard, 
letterbomb) to MacTutor Magazine, at PO Box 400, Placentia, 
CA 92670, c/o Romper Room. We'll do our best to publish and 
answer your question. 

If you are developing (or thinking about developing) a full- 
blown Mac application (commercial or otherwise), then you 
should think about joining our Certified Developer Program. 
Certified developers get put on our mailing list and have access 
to MacDTS to help answer their questions on a personal level. То 
inquire about becoming a Mac Certified Developer, contact the 
Developer Programs group at Apple Computer at 
(408) 973-4897. 

Since we don'thave your questions yet, this month's column 
contains information that was presented at the January 
MacWorld Expo in San Francisco. The first is Chris Derossi's 
presentation on MultiFinder compatibility, and the second is 
from the handout from Fred Huxham's presentation on writing 
code to be compatible with Apple's AU/X, both given at the 
MacTutor session at the San Francisco MacWorld Expo last 
January. 

MultiFinder Programming Tips by Chris Derossi 
Be MultiFinder Aware 

Generally, being compatible with MultiFinder is easy, and 
mainly involves following the guidelines outlined in Inside 
Macintosh and the TechNotes. Being MultiFinder aware is 
another issue. MultiFinder awareness is actually not that diffi- 
cult, and requires justa few things: a SIZE resource that describes 
your application's knowledge of MultiFinder (see below), code 
to handle Suspend/Resume events, and sharing time with other 
applications by using WaitNextEvent. 
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omper Room Refugees 


(a.k.a. Macintosh Developer Tech Support) 


Chris Derossi 
Fred Huxham 
MacTutor Vol. 4 №. 3 


Applications running under A/UX using the Toolbox 


Application running under A/UX 


Macintosh OS Manos User 
Subset ace 
Toolbox 


Standard A/UX 
Libraries 


New Adventures in Programming: A/UX 2 


Fig. 1 Apple's A/UX environment 


With Suspend/Resume events, your application can deter- 
mine when it is running in the foreground or the background. In 
the background, your application should run as normal, but it 
shouldn’t expect any events other than update events, and it 
shouldn’t do anything that would pull the rug out from under the 
foreground application (like changing its cursor). 

To do background processing, your application should di- 
vide its background tasks into small chunks. Each time that your 
application gets background time, it should do one piece of its 
task, and then relinquish the processor again by calling GetNex- 
tEvent or WaitNextEvent. 

When your application is in the foreground and it is waiting 
for a user event, it should call WaitNextEvent. This gives 
processor time to the background applications. 

Handle ALL Events 

Under MultiFinder, your application cannot prevent itself 
from being switched out by masking Suspend/Resume events 
(App4Events). If you mask out Suspend events, you will still be 
switched out; you just won’t know that it happened. 

Be prepared to handle Update events at all times. While 
suspended, your windows may need updating when other win- 
dows are moved. MultiFinder will pass Update events to your 
suspended application until the update is performed (or until 
MultiFinder has tried so many times that it decides you're never 
going to handle the event). 

Share The File System 

Now that the Finder and other applications use the-File 
System during the execution of your program, you have to pay 
particular attention to your use of files. The best tip is to always 
use the file's refNum, and never rely on the file name or the 
pathname of the file after it has been opened. Other applications, 
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or even the user with the Finder, may rename and move the file 
after you have opened it, but the refNum will stay valid. 

If you need to get the name or directory of an open file, call 
GetFCBInfo (not available on 64K ROMs) each time that you 
need it. 

Since files that are not open can be deleted or changed, if you 
need a file to remain undeleted and unmodified, keep it open. If 
you open a file, read from it, then close it, the next time that you 
try to access that file, it may have been deleted, renamed, moved, 
modified, or opened by someone else. 

And above all, CHECK ERRORS! Because you're sharing 
the File System, you may not have exclusive use of it. This means 
that, even though you have only a few files open, for example, 
you may get a tmfoErr (Too Many Files Open Error). Similarly, 
youcould geta tmwdoErr (Too Many Working Directories Open 
Error). And even if you've closed all of your files on a volume, 
UnmountVol will now return an error if other files are open. 

Use The Right A5 

In general, register AS, which points to your QuickDraw 
world and to your application's global variables, is only valid 
when your application's main code is running. Auxiliary pieces 
of code thatare separate from the application (like MDEFs, VBL 
tasks, Time Manager routines, completion routines, etc) are not 
guaranteed to have your application's A5; they may be executed 
while A5 points to some other application's globals. 

When such code gets executed, you should first save register 
А5, and then load А5 with the one from your application. This 
will let you get to your application's variables, routines, and 
QuickDraw world. When your code has completed, be sure to 
restore А5 to the value it had when your routine was called. 

Use The Clipboard For Cut, Copy, and Paste 

Since many applications may be running, your application 
should not use the scrap for private data storage. If your applica- 
tion changes the scrap on its own, not in response to a user's Cut 
or Copy, the user may see the Clipboard change unexpectedly in 
other applications. 

On the other hand, by fully supporting Cut, Copy, and Paste 
with the scrap, your users will be able to easily move data among 
applications. 

Understand When & What Happens WhenSwitching 

When MultiFinder does a context switch from one applica- 
tion to another, it swaps out the following things: 

• Low-Memory—System-Wide Globals 
* 68000 Registers (Including A5 and A7 for globals and the 

Stack) 

° The Application 's Layer—AIl of the application's windows 
° Trap Patches that were made from within the application 

* VBL Tasks in the application heap 

* Drivers in the application heap 

* Time Manager tasks in the application heap 

There are three cases where MultiFinder will do a context 
switch. The first, and most obvious case occurs when the user 
clicks on a suspended layer, chooses a suspended application 
from the Apple menu, or clicks on the small icon in the right side 
of the menu bar. This causes a full context switch, bringing the 
resuming application's layer to the front. 
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This full context switch won't occur under two conditions: 
when the front window of the foreground application is a 
dBoxProc (standard modal dialog window), and when there are 
pending file system calls. (When the file system calls complete, 
the switch will happen.) 

MultiFinder checks the front window's proc ID to determine 
if it’s a modal dialog. So dBoxProc windows should only be used 
for modal dialogs. Using this window type for other purposes will 
block the switching mechanism. (If you like the look of the 
dBoxProc, you can use a plainDBox, and draw the additional 
thick line yourself.) 

The second two context switches can happen ANY time that 
GetNextEvent, WaitNextEvent, or EventAvail is called, even 
from a modal dialog. Neither of these switches changes the 
ordering of the layers, or generates Suspend/Resume events. One 
Switch is for giving time to background applications, and the 
other is for passing update events to suspended applications. 
MultiFinder will only give background time to those applications 
that have the CanBackground bit set in their SIZE resource. ALL 
applications get background update events as needed. 

The SIZE Resource 

Even if your application is not going to do background 
processing, it should have a SIZE resource. In addition to telling 
MultiFinder what MF features your application supports, the 
SIZE resource also specifies how much memory your application 
needs. If you don't have a SIZE resource, MultiFinder gives it a 
default partition size of 384K, which may be way too much or 
way too little for your app. 

The SIZE resource must have an ID of -1 and contain the 
following data: 

Flags Integer (16 bits) 

Preferred size  LongInt 

Minimum size  LongInt 

The flags word is a series of 5 boolean values and 11 unused 
bits. All unused bits MUST be set to zero for future compatibility. 
The bits are assigned as follows: 

Bit 15  dontSaveScreen/saveScreen 

This is included for Switcher compatibility only 
Bit 14 ignoreSuspendResumeEvents/acceptSuspendRe- 
sumeEvents 

Set this bit if your application understands Suspend and 
Resume events. 

Bit13 enableOptionSwitch/disableOptionSwitch 

This is included for Switcher compatibility only 
Bit 12  cannotBackGround/canBackGround 

Without setting canBackground, your application will not 
get nullEvents while it is suspended. 

Ви 11 dontDoOwnActivate/doOwnA ctivate 

If this bit is set, then your application accepts the responsi- 
bility for deactivating and activating its own windows when the 
application is suspended and resumed. This field may also be 
called notMultiFinderAware/MultiFinderAware. This bit 
should only be set if bit 14 is also set. 

The preferred and minimum sizes are the number of bytes 
that your application needs. So if your application runs best with 
512К of RAM, but will survive with only 128K of RAM, then the 
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preferred and minimum sizes would be 524288 (512K) and 
131072 (128K). 
How to be A/UX Friendly 
by Fred Huxham 
In figure 1 we see how applications running under Apple's 
version of Unix, called A/UX, can use the Macintosh toolbox to 


implement the Macintosh User Interface Guidelines. The Unix 


program makes a toolbox call, which is routed to a A/UX toolbox 
ROM interface routine, which in turn calls the trap in the 
Macintosh ROM. A subset of the Macintosh OS traps are also 
provided with an interface, so that OS traps get routed to standard 
A/UX libraries, to perform the expected Unix function, both for 
OS calls from the toolbox, and from the User’s application. The 
purpose of the Mac interface is to provide an environment that 
will run the following: 
e Macintosh Binaries 
• Unix Applications with toolbox enhancements 
e Macintosh / A/UX Applications 
Here are some things to keep in mind when designing for A/ 
UX compatibility: 
е Differences in execution environments 
° Memory Manager 
е File Manager 
е Differences іп C Compilers 
e Differences іп Language Conventions 
Here are some more notes on the remaining slides. 
Slide #5 
* 32-bit Address Violations 
Directly accessing the flag bits on relocatable blocks is a fate 
worse than death. The Macintosh OS only uses the low-order 24 
bits of an address. The high-order 8 bits are used as flag bits 
(Lock, Purge, Resource). A/UX however, uses full 32-bit virtual 
addressing. If an application directly manipulates one of the 
upper 8 bits of an address under A/UX, it invalidates the address. 
• CPU Privileged Instructions 
The A/UX Toolbox is run by an A/UX process in User 
Mode. Because of this, applications cannot make privileged 
instructions. Some MacOS applications move to and from the 
status register. If the motivation is to access the condition code 
bits, it is possible to do this by using the MOVE CCR,<ea> 
instruction. Because this is only available on a 68020, you must 
check to see that is what you are running on. If you are accessing 
the SR to turn interrupts on or off, you’re out of luck, only the 
kernel can do that. 
• Direct Hardware Access 
Under A/UX only the kernel is allowed direct access to the 
hardware. This means applications cannot: 
е Access the serial port by talking to the SCC’s 
registers. 
е Access the disk drive by talking to the disk control- 
ler chip. 
е Access any of the low-memory CPU exception 
vectors. 
In addition, not all the low-memory globals are valid under 
A/UX. Most that are not related to hardware are supported. 
• Initialization Routines 
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Differences in Execution Environments 


e 32-bit Address Violations 


• CPU Privileged Instructions 


• Direct Hardware Access 


ғ Initialization Routines 


е Newline Character 


New Adventures in Programming: A/UX 5 


Make sure call InitDialogs and TEInit. 

eNewline Character 

In the Macintosh environment, lines are terminated with a 
return (OXOD). In the A/UX environment, lines are terminated 
with a linefeed (0x0A). 

Slide # 6 

е Heap Zones 

There is no distinction between the system heap zone and the 
application heap zone. Тһе routines SystemZone and Ар- 
plicZone return the same pointer. 

* Master Pointers 

Under the A/UX OS, master pointers are 8 bytes long, rather 
than the 4 bytes used by the Macintosh OS. 

* Internal Data Structures 

The internal data structures of the Memory Manager are 
different from those in the MacOS. The heap zone header record 
is the same, but not all fields are used. An application should not 
attempt to traverse the blocks in a heap zone. 

е Memory Query Routines 

A/UX supports virtual memory, but the Mac memory man- 
ager routines are designed for a system that has a known amount 
of physical memory. Atthe current time, memory query routines 
such as FreeMem return the amount of memory that would be 


Memory Manager 


¢ Heap Zones 
е Master Pointers 


ғ Internal Data Structures 


е Memory Query Routines 


New Adventures in Programming: A/UX 6 
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available if your application had started with 1 MB of free 
memory. 
Slide # 7 
* Filename Conventions 
Applications running under A/UX must follow the A/UX 
filename conventions: 
e  ]4-character names. 
° The character / instead of : to separate directories. 
° A smaller range of legal characters. 
e Case sensitive filenames. 
е Resource and Data Files 
In the MacOS, both resources and data appear in separate 
forks of the same file. In A/UX, resources appear in a separate 
file, with the filename extension “res”. 
е Volumes 
Under A/UX, all Macintosh files exist on a single, emulated 
Mac volume. 
° Search Paths 
Unlike the MacOS, under A/UX a file must be in the 
specified directory or it will not be found. No alternative paths 
are searched. 
eGlobal Variables 
Only the following File Manager low-memory globals are 
supported: 
BootDrive 
VCBQHdr 
DefVCBPtr 
DrvQHdr 
FSFCBLen 


File Manager 


e Filename Conventions 


е Resource and Data Files 


« Volumes 


• Search Paths 


• Global Variables 
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Slide # 8 

е Multicharacter Constants 

The two C compilers evaluate character constants in oppo- 
site order. For example, the A/UX C compiler converts ‘ABCD’ 
to 0x44434241, and the MPW C compiler converts it to 
0х41424344. Multicharacter constants are used commonly to 
define resource types. 

° Spurious Warnings 

The A/UX compiler generates warnings when it sees zero- 
length arrays, which appear frequently in the include files. 
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Differences in C Compilers 


е Multicharacter Constants 


e Spurious Warnings 


* Pascal Function Types 


* Enumerated Types 
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• Pascal Function Types 

MPW C has an extern pascal function type used for calling 
most of the ROM routines. To use these same functions, an A/ 
UX C program must use assembly glue. 

* Enumerated Types 

In MPW C, enumerated types can be 8, 16, or 32 bits long, 
depending on the range of possible values. In A/UX C, enumer- 
ated types are 32 bits long (unless packed in structures using 
bitfields). 

Slide #9 

* Pascal vs. C Strings 

Many of the ROM routines follow Pascal conventions for 
storing strings, pushing parameters on the stack, and returning 
function results. the conventions differ from standard C conven- 
tions. The A/UX Toolbox includes conversion code that takes 
care of most of these incompatibilities as long as you use A/UX ` 
Toolbox routines for storing and retrieving data. However, 
strings in resource files and in A/UX Toolbox data structures are 
all stored as Pascal strings. 


Differences in Language Conventions 


* Pascal vs. C Strings 
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VIP Views 


Calculating Distance for Navigation 


V.I.P. 2.2 


Mainstay has released version 2.2 which is a significant 
upgrade and is free to all registered owners. V.I.P. 2.2 includes 
25 additional procedures, improved keyboard control, 5 new 
intrinsic functions to provide added flexibility in handling Point 
and Rectangle objects, and the ability to create a true “About...” 
under the Apple menu. If you are a V.I.P. owner and haven't sent 
in your registration card, you are missing some neat features. 


In the beginning 


In a previous article (April 1987), I presented a ‘shell’ 
program which implemented some of the common user interface 
actions e.g., Menus, Windows, File handling, and Events. In this 
program you will see that the same routines are used. In some 
cases these routines have been expanded to handle the specifics 
required of our program, and of course additional routines have 
been added. The only change brought about by changes to V I.P. 
itself is the ‘About’ routine, which is now called Gee Whiz. As 
mentioned earlier V ІР. programmers can now create a “About 
(program name)" entry under the Apple menu and have it display 
whatever they choose. In this case selecting ‘About GC. Dist..." 
displays the same window and information as presented at 
program startup. 


The guts and feathers 


The purpose of this program is to illustrate by example some 
of the most commonly used procedures. In addition to the 
already explored subjects we will create Dialogs, obtain user 
input data organized as records and save them to disk, work with 
some of V.I.P.’s intrinsic functions, and most importantly, һауе 
some fun programming. As is the case with most programs there 
is certainly more than one way to accomplish a particular objec- 
tive. WhatIpresent here is notadvocated as the only way, or even 
the best way, to do the job. In fact I violate a few of the rules set 
forth in Inside Macintosh, and ГИ tell you about them as we 
proceed. 


How far is it? 


This program computes and displays the Great Circle dis- 
tance between any two cities in the data file. Figure 4 contains 
the data required, which is input using the dialog as shown in 
figure 1. The Great Circle distance, in case you didn't know, is 
the shortest distance between any two points on a sphere. It is 
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Enter new records 
City Code: 
Latitude: 


Longitude: 
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Figure 1 Our Dialog Box 


most commonly used to represent the distance in nautical miles 
between airports for payload/range, performance, and fare cal- 
culations. Airports are each identified by a unique three character 
code. Los Angeles International airport, for example is LAX. 
The position on the globe of each airport is given as a latitude and 
longitude usually expressed in degrees and minutes. Latitudes 
south of the equator, and longitudes west of Greenwich, England 
are identified as negative angles. To work with these data, 
degrees and minutes are converted to decimal degrees, and to 
cope with SANE’s handling of some intrinsic functions, a con- 
version of decimal degrees to radians and vice is also required. 


Learning to love rectangles 


Three dialogs are used in this program. Record_Dialog, 
which is used to input the city code, latitude and longitude data. 
Edit_Dialog, which allows viewing and editing of the records 
previously saved to disk, and Input_Dialog for the user to specify 
the origin and destination city codes as input to routines for 
calculating the great circle distance. 

V.I.P. allows the programmer to create dialogs using built in 
procedures as I have done in this example, or as resources created 
with a resource editor such as ResEdit or Dialog Creator. The 
difficulty in using V.I.P.'s procedures to create dialogs is in the 
visualization and placement of the various rectangles which 
bound each dialog item. Dialogs can contain static text, editable 
text, radio buttons, check boxes, and ordinary buttons, each 
situated within a rectangle. Creating complicated dialogs using 
V.LP.’s procedures is enough to discourage ordinary mortals, but 
there is an easy solution even if you don’t care about resources. 

My approach 15 to use Dialog Creator. Dialog Creator by 
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Michael Bayer of Apple Canada lets you create dialog templates 
and dialog item lists interactively. It's asimple matterto draw the 
dialog then print the text source file which gives you the coordi- 
nates of each rectangle and the assurance that your dialog will 
look OK. 

For each of the three dialogs used in this program the code 
is essentially the same. A rectangle is specified for the size and 
location of the dialog window, and the new dialog procedure 
follows with arguments for rect, title, and dialog name. Entering 
a text string as the title argument indicates the dialog is to be non 
modal. Set rect and append dialog item procedures are now 
repeated for each item in the dialog. When referring to dialog 
items, their order of appearance in the dialog item list (DITL) is 
used. 

By convention, dialog item #1 is the default action to be 
performed when the user presses the return or enter key generally 
signifying OK. (Note; this default action is implemented 
automatically in V.I.P. for modal dialogs only) When all dialog 
items have been appended to the list, the open dialog procedure 
displays the dialog on the screen. If you prefer to create dialogs 
as resources, then you will need to change all occurrences of kill 
dialog to close dialog so as to not erase them from memory until 
Quit is selected. 


DoDialogEvent 


Now that we have our dialogs created, we need to be able to 
process the information entered or displayed according to the 
users action. For example, in the dialog as shown in figure 1, you 
can see there are three editable text fields and two buttons. Data 
entered by the user in the text edit fields is saved to disk when the 
‘Save it’ button is clicked, or conversely, the dialog is dismissed 
whenever the ‘Quit’ button is clicked. 

The DoDialogEvent routine receives two input arguments, 
i.e. Dialog and item to direct the action to be taken depending on 
which dialog is active and which item of the dialog was selected. 
In this case the first if logic form is true, and program flow is 
directed to the Get. Record routine when item=1, and to the kill 
dialog procedure whenever item-2. Actions to be performed by 
the other dialogs are similarly handled. 

The purpose of handling all dialog events in one routine is 
probably not apparent in this small program. However, this 
routine like those presented in my previous article, are really 
generic, in that they don't do any real work, but merely direct 
program flow to a routine specifically designed to perform a 
discrete task. Programs written using a structured approach are 
usually easier to modify and are certainly easier to debug. 


Get Record 


This routine when called by the DoDialogEvent routine 
simply executes three get dialog item procedures corresponding 
to the three text edit fields in the Record Dialog. If you count the 
items appended to Record, Dialog you will see that items 7, 8, 
and 9 are the text edit fields receiving user entries for City Code, 
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Review €& Edit Records. 


City Code: ORD 
Latitude: 4159 
Longitude: 


Record No.: 


Get Record Save Changes 


Figure 2 Editing our distance data base 


Latitude, and Longitude respectively. To assure the City Code is 
stored properly, the object ‘City’ is converted to upper case. 
When this routine has completed its miniscule tasks, program 
flow resumes in the DoDialogEvent routine and the 
Store_Records routine is called. 


Store_Records 


With the information the user has entered in Record_Dialog 
extracted by the Get_Record routine as a result of the user 
clicking the ‘Save It’ button, we are now going to save it to disk 
as arecord. A record, as I’m sure you know, is a group of related 
data organized in fields. In V.I.P., records themselves are 
identified by a Record Number, and individual fields are located 
within a record by specifying the offset (the number of bytes) 
from the beginning of the record. In preparation for storing the 
record to disk, the program decides if this is the first time its been 
asked to store a record, and if so, to display the standard file 
dialog, otherwise just save the record to disk without further ado. 
The first procedure sets the value of n according to how many 
times the routine is accessed, and is used as an argument to the 
object RecNo[n] which serves to automatically number our 
records. 

The if (flag) logic form checks for true and directs execution 
flow accordingly. So, let's say this is the first record to be stored. 
In thatcase Пар-0 or false, and execution continues with the first 
else logic form. The get document name procedure displays the 
standard file dialog with the prompt, “Save file as *Cities'". 
Here's my first transgression from the scriptures of Inside Macin- 
tosh. Rather than allowing the user to name the file anything he 
(she) wishes, I tell ‘ет name it ‘Cities’. If this offends your 
sensibilities, please feel free to change the code. Actually, you 
may name the file anything you choose. The argument name 
serves equally as the input argument, and its contents appear as 
the default name in the edit field reserved for the name of the file 
to be saved. To change the default name, initialize the global 
object ‘FileName’ to whatever you prefer, and don’t’ forget to set 
the array size at least equal to the string length plus 1. 

The user accepts ‘Cities’ as the name of the file to be saved 
and clicks OK to dismiss the dialog, and the open file procedure 
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The distance from LRH to LHR is 4727 Nautical miles. 


Select cities 


Enter city codes for Origin 0 Destination. 


Figure 4 Output of our distance program 


opens the filein the *write' mode. Theallocate record procedure 
allocates a record in memory with a length of 18 bytes, and 
identifies it with RecNo[n], which is now 1. 

City code is always 3 bytes plus 1 byte for end of string 
marker, the maximum length of Latitude and longitude is 6 bytes 
plus an additional byte for end of string. All data making up the 
record is stored as a continuous text string with the record length 
being the sum of each field plus an additional byte. 

Three put field procedures take the global objects, City, Lat, 
and Long, and position them within the record. Arguments for 
put field are; record number, byte offset, and field length. Byte 
offset is expressed in bytes and the first position ina record is byte 
position zero. Field length is also expressed in bytes and is sized 
to handle the longest entry anticipated. 

Procedures write record, free record, and close file complete 
the task of saving the record to disk. Now, because this is the first 
time this routine has been called, we set the value of flag to 1 or 
true. An alert is displayed informing the user that additional 
records added during this session will be saved without the 
GetFile dialog. Three set dialog item procedures clear the 
previously entered data, and position the text edit caret in the first 
text edit field ready for entry of the next record. 

Assuming the user continues by entering data for the next 
record; when the Save It button is clicked, program flow pro- 
gresses exactly as before. The difference is, when Store Records 
is called this time, the counter n is incremented and the first if 
logic form now evaluates to true. The open file procedure opens 
the file *FileName', and the get document length procedure 
returns the length in bytes of the file in the object ‘Position’. To 
avoid overwriting previously saved records, the file position 
procedure sets the file position according to the value of Position. 
From here on the same procedures are executed as before to save 
the record to disk. 


Origin: 


Destination: 


Review Records 


Let's say, for purposes of this tutorial, that you have entered 
all of the data and you wish to see if it is correct. By selecting 
View or Edit Records... from the Options menu, a non-modal 
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dialog is displayed as shown in figure 2, and the Review. Records 
routine is called. This short routine opens the file *FileName' in 
the read only mode. A for logic form provides a loop to be 
executed 10 times (NoRecs is a constant assigned the value of 
10). The allocate record and read record procedures contained 
within the for loop are thusly executed 10 times to bring the entire 
file into memory. For safety sake the file is closed, and the value 
of the object n is set to zero. 

When the Get Record button is clicked, the DoDialogEvent 
routine calls the Next Record routine. As you might have 
guessed, when the Save Changes button is clicked, DoDialo- 
gEvent processes the request by calling the Save Changes rou- 
tine. The dialog is ultimately dismissed by clicking the window's 
close box. 


Next Record 


This routine is simply a series of get field and set dialog item 
procedures to display the contents of the records saved in the file 
‘FileName’. To start at the beginning of the file, the object n is 
assigned the value of 1. Record Number is displayed by convert- 
ing the object n to a byte type array named string with the 
procedure number to string. Note, the minimum dimension for 
a byte type array to handle number to string conversions is 13. 

The Next, Record routine is called each time the user clicks 
the GetRecord button. When the last record has been viewed, the 
assign procedure within the if logic form is executed to set the 
value of the object n to zero. This merely allows the continuous 
viewing of records by starting again at record number 1 when the 
last record has been displayed. 


CITY CITY CODE | LATITUDE | LONGITUDE 


Figure 5 Our data base for distance calculation 
Save Changes 


While viewing the records, changes may be made by enter- 
ing the appropriate data in one or more of the text edit fields and 
clicking the Save Changes button. To no one's surprise, the 
Save, Changes routine is called by the DoDialogEvent routine 
whenever the Save Changes button is clicked. 

This routine simply opens the file *FileName' in the write 
mode and sets the file position to overwrite the record to be 
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changed. To do this, the procedure file position uses the argu- 
ment (n-1)*18. Or in plain English, subtract 1 from the record 
number because the record pointer is left at the end of the record 
we wish to change. Now multiply by the record length (18), to 
set the file pointer to the correct position as calculated from the 
beginning of the file. 

The actual writing of the record uses the same procedures as 
described previously. Two if logic forms are used to maintain 
correspondence with the actual record number, and if n=0 as is 
the case when the last record is the one to be edited, we simply 
assign the value of 10 to n. To make this a temporary measure, 
the object ‘flag’ is set to true, which is detected by the next if, and 
the value of n is once more zero. This only makes sense if you 
remember “п” will always be something between 0 and 9 when- 
ever this routine is called. So if n is equal to anything from 1 to 
9, just write the record, else if п=0 change it to 10 temporarily. 
There must be an easier way. 


Find City 


By selecting Compute Distance... from the Options menu, 
the dialog as shown in figure 4 is displayed. When the user enters 
the city codes for the origin and destination cities and clicks the 
Do It button, the Find City routine is called by the Get Input 
routine, and receives Origin and Destination as input arguments 

The first thing this routine does is check to see if you are 
trying to fool it by entering the same city code for both the origin 
and destination cities. Normally an input like this should result 
in a distance of zero, but for some reason Apple's SANE doesn't 
like zero's as operands for certain intrinsic functions. So, rather 
than having the Find City routine complete all of its tasks, and 
then trap the error in the Calculate routine, I simply chose to 
display an alert informing the user of the problem. 

Find City opens the file *FileName', reads the records into 
memory, and then compares the City field in the firstrecord with 
the input argument Origin. If match=0 (are the same), two get 
field and string to number procedures extract and convert the data 
stored as Latitude and Longitude to numbers for the Origin City. 
When the origin city has been found, Пар! is set to true, and 
program execution continues looking for a match with the 
Destination city. 

In this manner, the maximum number of times the records 
are searched for both the Origin and Destination cities is equal to 
the number of records in the file. If either flag1 or flag2 is not set 
to true, an alert informs the user that his choice is not in the file, 
and execution of this routine is terminated with a return proce- 
dure. 

When both Origin and Destination cities have been found, 
Latitude and Longitude of the Origin and Destination cities are 

.now passed to the Calculate routine as A,B,C,D respectively, as 
are the Origin and Destination city codes. 


Calculate 


If you haven't fallen asleep by now, I' m sure you recall the 
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data we stored as Latitude and Longitude represented degrees 
and minutes which were actually stored as byte arrays and later 
converted to real numbers by the Find City routine. So, for 
example, the Latitude of LAX we entered was 3356 with the 
rightmost two characters representing the minutes portion in 
every case. 

When the object A is received in this routine, and assuming 
LAX is the Origin city, it would appear as 3356.000 if we were 
to examine its value. To extract the minutes portion of this 
number we simply divide by 100 to move the decimal point two 
places to the left, and use the int & fract procedure to separate the 
integer and fractional portions so we can convert the fractional 
portion to decimal degrees. By dividing the fraction by 60 and 
multiplying by 100, and adding the fractional part now in decimal 
degrees to the integer we have a number we can almost work 
with. 

This same series of manipulations is completed for objects 
В,С, and D, and now because SANE utilizes radians when 
working with sin, cos, and acos, we need to do another conver- 
sion. By multiplying each object A,B,C,D by (pi/180) we аге 
finally ready to do the calculation to see how far it is between our 
Origin and Destination cities, however the answer wont make 
any sense until we convert the result ‘Dist’ to Nautical Miles. The 
distance is rounded off to the nearest whole number, converted 
to a string, and a series of draw string procedures displays the 
results as shown in figure 3. 


Odds & Ends 


If all of this seems like the long way around to arrive at the 
shortest distance between two points, you are probably correct. 
In this example program with only 10 cities we could have as 
easily entered Latitudes and Longitudes in a form that would not 
require conversion. However, when considering there are over 
6900 airports in the world, each with its own identifier and 
Latitude and Longitude, you can perhaps appreciate the simplic- 
ity of using whole numbers to represent degrees and minutes 
rather than complex numbers more easily assimilated by a 
computer. 

One routine we didn't talk about this time is DoCloseBox. 
This routine is fairly straightforward, and performs the chores of 
disposing of the various windows and non modal dialogs used by 
the program. The only thing worth mentioning is my solution to 
avoid the possibility of opening the same window twice. In the 
DoOptions routine you will see that I have inserted a disable 
menu item procedure which globally disables the Options menu 
whenevera routine using a window is called. While this isn't the 
most elegant way of avoiding the embarrassment of not being 
able toclosea window, it works. An enable menu item procedure 
in the DoCloseBox routine is executed to restore the Options 
menu after the current window is closed. 

That about does it for this time. I hope what you have read 
here is helpful in learning Visual Interactive Programming. If 
you would like to see other V.I.P. stuff, write to MacTutor! In the 
meantime have fun, after all that's what it's all about. 
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Bain 
66-0134 program for MacTutor™ 
by Bill Luckie © 1987 


Visual Interactive Programming 


V.I.P. by Dominique Lienart, published by Mainstay. 


DoSetup 
while C! Quit) 
DoSelect 

exit 


Calculate (4,8,C,D, Origin, Destination) 


-) real А 

-> real В 

-) real С 

=) real D 

—› byte Origin(4] 

— byte Destination[4] 


521131 


integer 
Distance 


Dist 
fraction 
integer 


rectangle 


r 


assign (A / 100,A) 

int & fract CA, integer, fraction) 
assign (fraction / 60 * 100,frection) 
assign (integer + frection,A) 
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assign (B / 100,B) 
int & fract (B, integer, fraction) 
assign (fraction / 60 * 100,fraction) 
assign (integer + fraction,B) 
assign (С / 100,00 
int & fract СС, integer, fraction) 
assign (fraction / 60 * 100,fraction) 
assign Cinteger + fraction,C) 
assign (D / 100,0) 
int & fract (D, integer, fraction) 
assign (fraction / 60 * 180,fraction) 
assign Cinteger + fraction,D) 
assign CA * (pi/1802,A) 
assign (В * (р1/180),В) 
assign (С * (pi/180),C) 
assign (D * (рі/180),0) 
assign (68*acos(sin(A)*sin(C)+cosCA)*cos(C)*cos(D-B)), Dist) 
assign (Dist * (1/р1 * 188),Dist) 
int & fract (Dist, integer, fraction) 
if (fraction > .5) 

assign Cinteger + 1,Distance) 
else 

assign Cinteger ,Distance) 
number to string (761” Distance, S2) 
activate window (Window) 
set text font (0) 
move to (50,18) 
draw string (“The distance from 4,0) 
draw string (0гідіп,02 
draw string C“ to 4,00 
draw string (Destination, 8) 
draw string (^ is ",0) 
draw string (52,0) 
draw string С" Nautical miles.^,9) 


DoAbout 


ID 

go 
message 
type 


location 


rectangle 
Por trect 
Windowrect 


assign (0,00) 
set rect (60,60, 120,450,Windowrect) 
set rect (0,0, 120,450, Portrect) 
new window (4,9, 1,Windowrect,Portrect, ^^, Window) 
set text font (0) 
move to (15,85) 
draw string (*GC Dist program for MacTutor"^,0) 
move to (30,145) 
draw string (^ by Bill Luckie.^,0) 
move to (45,168) 
draw string (^9 19877,0) 
if CAboutF lag) 
while C! go) 
get next event (type, location, message, ID) 
if (type = 3) 
assign (1,90) 
else 


else 

wait (90) 
kill window (Window) 
assign (1, AboutF lag) 
assign (8, Window) 
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DoCloseBox 


get window (WhichWindow) 
if (WhichWindow = AboutWindow) 
kill window CAboutWindow) 
assign (0, AboutWindow) 
else 
if CWhichWindow = InputWindow) 
kill window (Window) 
assign (Ø, Window) 
kill dialog CInputDialog) 
assign (Ø, InputWindow) 
assign (Ø, InputDialog) 
else 
if CWhichWindow = EditWindow) 
kill dialog CEditDialog) 
assign (0,EditWindow) 
assign (0,EditDialog) 
else 


enable menu item (Menu[3],8) 


DoD ialogEvent (Dialog, item) 


— byte Dialog 
— byte item 


if (Dialog = RecordDialog) 
switch Citem, 1,2) 
case 1 
Get_Record 
Store.Records 
case 2 
kill dialog (RecordDialog) 
assign (8, RecordDialog) 
default 


else 
if (Dialog = InputDialog & item = 1) 
Get Input 
else 
if (Dialog - EditDialog) 
switch Citem, 1,2) 
case | 
Next_Record 
case 2 
Save. Changes 
default 


DoEdit (item) 


— byte item 
switch Citem,3,4,5,6) 
case 1 

cut text 
case 2 

copy text 
case 3 

paste text 
case 4 

clear text 
default 


DoFile Citem) 
ә byte item 
byte 


result 


switch Citem, 1,2,4) 
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if CAboutWindow) 
print text CAboutWindow) 
else 


alert C1,"There is no window to print from.^,result) 


case 3 
assign C1,Quit) 
default 


DoMenuSelect Степи, i tem) 


— byte menu 
— byte item 


switch Cmenu,Menu[11,Menu(2] , Menu[ 31) 
cese 1 
DoFile Citem) 
case 2 
DoEdit Citem) 
case 3 
DoOptions Citem) 
default 


DoOptions (item) 
-» byte item 


switch Citem, 1,2,3,5) 

case 1 
Record Dialog 

case 2 
disable menu item (Menu(31,0) 
Edit Dialog 

case 3 
disable menu item (Menu(31,0) 
Input Dialog 

case 4 
disable menu item (Menu(31,0) 
Gee Whiz 

default 


DoSelect 


Event ID 
EventMessage 
Event Туре 


point 


MouseLocat ion 


get next event C(EventType, MouseLocat ion, EventMessage , Event ID) 


Switch CEventType, 1,4,5) 
case 1 
if CEventMessage=9 & EventID=1) 
DoAbout 
else | 


DoMenuSelect (EventMessage, Event ID) 


case 2 

DoC loseBox 
case 3 

DoDialogEvent CEventMessage, EventID) 
default 


DoSetup 


new menu C*File^,MenuL 11) 


append menu item (MenuL 11, “Раде Setup. ..;Print...;(-;Quit/Q^) 


new menu C*Edit^,Menu(21) 


append menu item (Мегы[21, *CUndo/Z; (- ; Cut /X; Copy/C;Paste/ 


V; Clear") 
new menu C*Options^,Menul 31) 
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append menu item (Menu[3],*Create new Records...;View ог Edit 


Records...;Compute Distance...;(-;Gee Whiz Stuff...”) 
DoAbout 


Edit.Dialog 
rectangle 


r 


set rect (100, 106,250,406,r) 

new dialog (r,“Edit Records”, EditDialog) 

set rect (111,23, 144, 116,r) 

append dialog item (EditDialog, 1,г, "Get Record”) 
set rect (111,179, 144,280,г2 

append dialog item CEditDialog, 1,r, "Seve Changes”) 
set rect (3,72, 19,228,r) 

append dialog item (EditDisalog,4,r, "Review & Edit Records.” ) 
set rect (27,50,43, 150,г) 

append dialog item (EditDialog,4,r, "City Code:^) 
set rect (47,50,63,150,г2 

append dialog item (EditDialog,4,r, "Letitude:") 
set rect (67,50,83,150,г2 

append dialog item C(EditDialog,4,r,"Longitude:^) 
set rect (87,50, 183, 156,r) 

append dialog item (EditDialog,4,r, ^Record No.:^) 
set rect (29, 199,45,217,r) 

append dialog item (EditDialog,5,r,"") 

set rect (50, 190,66,240,г) 

append dialog item CEditDialog,5,r,"") 

set rect (71,190,87,240,г) 

append dialog item (EditDialog,5,r,"^) 

set rect (88, 138, 104, 158,r) 

append dialog item (EditDialog,5,r,"^) 

open dialog CEditDialog,EditWindow) 

Review Records 


Find.City (Origin, Destination) 


=) byte Origin[4] 
-> byte Destination[4] 


byte 
f 


flag! 
f lag2 
match 
n 

result 


integer 
RecNol[ 10] 


compare string COrigin,Destination, match) 
if (match = 0) 
alert C1,"The Origin and Destination cities are the 
same.” result) 
return 
else 


assign (0,flag1) 
assign (0,flag2) 
open file (FileName, 1,”TEXT”,f) 
for (п, 1, NoRecs, 1) 
allocate record C18, RecNo[n1) 
read record (f ,RecNo[n]) 
close file Cf) 
Гог (n, 1, NoRecs, 12 
get field (n,0,4,City) 
upper case (City) 
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compare string (City, Origin ,match) 
if (match - 0) 
get field (n,4,T,Lat) 
string to number (3,Lat,A) 
get field (n,11,T,Long) 
string to number (3,Long,B) 
assign C1,flagl) 
else 


compare string (City, Destination, match) 
if (match = 8) 

get field (n,4,7,Lat) 

string to number (3,Lat,C) 

get field (п, 11,7,Long) 

string to number (3,Long,D) 

assign (1, flag2) 
else 


if (| flag) 


alert C1,"Sorry, Origin city code not in file.” result) 
return 


else 
if СІ flag2) 
alert C1,"Sorry, Destination city code not in 
file.^,result) 
return 
else 


Calculate (A,B,C,D, Origin, Destination) 


Gee_Whiz 
AboutF ile 


rectangle 
PortRect 
WindowRect 


set rect (50,40,312,472 WindowRect) 

set rect (0,0, 1000, 432, PortRect) 

new window CT, 1, 1,WindowRect,PortRect, “Gee Whiz 
Stuff ^, AboutWindow) 

open file (*Gee.Whiz^, 1, “ТЕХТ, AboutF ile) 

load text CKAboutF ile, AboutWindow) 

close file CAboutFile) 


Get_Input 


Destination[4] 
Origint4] 
stete 


clear window (Window) 

get dialog item CInputDialog, 4,state, Origin) 
upper case (Origin) 

get dialog item CInputDialog,5,state, Destination) 
upper case (Destination) 

Find_City COrigin,Destination) 


бей. Record 
byte 


state 


get dialog item (RecordDialog,7,state, City) 
upper case (City) 

get dialog item (RecordDialog,8,state,Lat) 
get dialog item CRecordDialog,9,state,Long) 


Input_Dialog 
rectangle 


r 
ri 


set rect (182,61,326,451,r) 
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new dialog (r ,“Select cities", InputDialog) 

set rect (196, 164, 137,221, r) 

append dialog item CInputDialog, 1,r,"Do it^) 

set rect (31, 104,47,204,r) 

append dialog item CInputDialog,4,r, “Origin: ^) 

set rect (62, 104,78,204,r) 

append dialog item CInputDialog,4,r, "Destination: ^) 
set rect (34,220,50,245,r) 

append dialog item CInputDialog,5,r, "^) 

set rect (60,220, 76,245,r) 

append dialog item CInputDialog,5,r, **) 

set rect (3,49,26,342,r) 

append dialog item CInputDialog,4,r, "Enter city codes for 
Origin k Destination. >) 

set rect (52,68,152,444,r) 

set rect (0,0, 155,447,г1) 

new window (4,0, 1,r,r 1, *", Window) 

open dialog CInputDialog,InputWindow) 


Next_Record 


result 
string[13] 


assign (n + 1,n) 
get field (RecNo[n1,0,4, City) 
set dialog item CEditDialog,8,9, City) 
get field (RecNo[n],4,7,Lat) 
set dialog item (EditDialog,9,9,Lat) 
get field (Кес№ [п], 11, 7,Long) 
set dialog item (EditDialog, 10,9, Long) 
number to string (^6b*,n,string) 
set dialog item (EditDialog, 11,9, string) 
if (п = NoRecs) 

assign (Q,n) 


else 
Record. Dialog 
rectangle 

r 


set rect (100, 154,251,359, r) 

new dialog (r,**,RecordDialog) 

Set rect (115,5, 147,85,r) 

append dialog item (RecordDialog, 1, г, "Save It^) 
Set rect (115, 119, 147, 199, r) 

append dialog item (RecordDialog, 1,r, "Quit^) 

Set rect (4,38,22, 176,r) 

append dialog item (RecordDialog,4,r, "Enter new records”) 
set rect (30,6,46, 106,r) 

append dialog item (RecordDialog,4,r,"City Code:^) 
set rect (60,6,76, 106,r) 

append dialog item (RecordDialog, 4,r, "Latitude: ^) 
set rect (90,6, 105, 106,г) 

append dialog item KRecordDialog,4,r, “Longitude: ^) 
set rect (30, 105,46, 140, r) 

append dialog item (Кесога0 іа1од,5,г,**) 

set rect (60, 105,76, 162, r) 

append dialog item (RecordDialog,5,r, ^^") 

set rect (90, 105,106,162,г) 

append dialog item K(RecordDialog,5,r,"^) 

open dialog CRecordDialog, RecordW indow) 


Rev tew_Records 


in r 
result 
open file (FileName, 1, "TEXT^,f) 
for (п, 1, NoRecs, 1) 
allocate record (18,RecNo[n]) 
read record (f ,RecNo[n]) 
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close file (f) 
assign (0,п) 


Save. Changes 
byte 


f 
stete 


result 


assign (0,f lag) 
open file (FileName,2, “TEXT”, f) 
if (n = 0) 
assign C10,n) 
assign (1,f lag) 
else 


file position (f,(n-1) * 18,0,result) 
get dialog item CEditDialog,8,state,City) 
get dialog item CEditDialog,9,state,Lat) 
get dialog item CEditDialog, 18,state,Long) 
allocate record (18,RecNo[n]) 
put field (RecNo[n],8,4,City) 
put field (RecNo[n],4,7,Lat) 
put field (Кес№ [п], 11,7,Long) 
write record Cf ,RecNo([n)) 
close f ile (f) 
if (flag) 
assign (8,n) 
else 


Store..Records 
byte 


f 
ok 
result 


Position 
Кес№ 10] 
status 


assign (п + 1,n) 
if (flag) 
open file (FileName,2, "TEXT^,f) 
get document length (FileName,Position) 
file position Cf,Position,O,status) 
allocate record (18,RecNo[n]) 
put field (RecNo[n],8,4,City) 
put field (RecNo[n),4,7,Lat) 
put field (RecNoIn], 11,7,Long) 
write record (f ,RecNo[n]) 
free record (RecNoI[n]) 
close file Cf) 
else 
get document пате (1, "Save file as 
‘Cities’”, “TEXT”, ok, FileName) 
if Cok) 
open file (FileName,2, “TEXT”, Г) 
allocate record (18,RecNo[n)) 
put field (RecNo[n],8,4,City) 
put field (RecNo[n],4,7,Lat) 
put field (Кес№ [п], 11,7,Long) 
write record (f ,RecNo[n]) 
free record (RecNo[n]) 
close file (f) 
assign C1,flag) 


alert C1,"Additional records added during this session 


will be saved without the GetFile dialog.” ,result) 
else 


set dialog item (RecordDialog,7, 1,22) 
set dialog item (RecordDialog,8,9, **) 
set dialog item (RecordDialog,9,9,””) 


Mac Hardware 


MacBox and the Serial Sermon 


Once upon atime in a galaxy far, far away...a humble servant 
of Big Byte took upon himself the serial expansion of the blessed 
Mac. However, before enlightenment was acheived, much 
wisdom had to be revealed unto and understood by the humble 
servant. In fact, much self-flagellation, usually with an RS-232 
cable, was necessary to gain the wisdom needed to successfully 
expand the Mac's serial ports. 

Allhi-tech parables aside, my travail resulted from the desire 
to have my Mac talk to my modem, an X-10 Powerhouse 
appliance controller and a Radio Shack Model 100 portable 
computer, and do so without going through a cable swapping 
boog-a-loo. This was accomplished with an inexpensive switch 
and some simple wiring. I've included some pictures and dia- 
grams to help the more ambitious (and cheap, Mac switch boxes 
are commercially available) of you duplicate the task. 

Excluding the SCSI port and the second disc drive port, the 
Mac talks to the world through two serial ports. One of these 
serial ports is usually configured through the Chooser software 
to talk to the Imagewriter. The other port can be configured by 
Chooser as an Appletalk connection, or, using communications 
software such as Red Ryder, as a modem port. Also, using an 
adaptor box and MIDI software, these serial ports can talk to 
musical instruments such as a DX-7 sythesizer. Finally, one of 
these ports can be used to talk directly to another computer 
without the modem/phone line connection assuming both ma- 
chines are in close proximity. Some computers, such as the 
Incredibly Bad Machine and the Model 100, normally talk to 
printers through a parallel port; however, the Imagewriter/Mac 
combo do it serially. 

The RS-232 data communications standard is used by most 
personal computer systems for data transfer. There is also 
Ethernet, Appletalk and others, but we're talking proletarian 
stuff here, not big-time University networking. The Mac uses an 
improvement of the RS-232 standard called RS-422. This 
improvementallows for longer cable lengths to carry digital data, 
necessary for Appletalk networks. Thankfully, RS-422 and RS- 
232 protocols are generally compatible. The RS-232 standard 
defines the DB-25 connector pinouts (check the diagrams in- 
cluded) as well as describes data terminal equipment (DTE) 
sending digital information to data communications equipment 
(DCE) over an analog phone line to another DCE-DTE combo 
(digital data poops out after 100 feet or so and must be converted 
to an analog signal for the long haul). DTEs are usually 
computers, while DCEs are modems. They are connected with 
straight cables, that is, the TXD pin on the DTE is connected to 
the same TXD pin on the DCE. The internal wiring of the 
equipment makes sure everthing is copesetic. The DTE/DCE 
pairs use software handshaking to control the communications 
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Fig. 1 TIFF Photo of the МасВох internals 


connection, usually XON/XOFF protocol. If one pair wants to 
pause communications, it issues a little ASCII data code ,Control 
Q, to tell the other pair to stop transmitting; a Control S resumes 
communications. If you ever used Red Ryder to access 
Сотри$егуе or Genie, you may have used the О and S radio 
buttons to control the information zipping across the screen at a 
rate faster than you can read it. 

However, as occurs with all good standards, they get modi- 
fied to accomplish new tasks. A problem arises when two 
computers are hooked back-to-back with no modem/phone link 
inbetween. Now you have a DTE-DTE link which confuses the 
signal lines on the interconnection cable. So you need a cross or 
“null” cable to connect the equipment. In such a cable, the TXD 
pin from one DTE goes to the RXD pin of the other DTE, and vice 
versa. If these DTE-DTE combos are a back-to-back computer 
pair, they usually use a form of software handshaking. However, 
ifa computer is talking toa printer (which usually acts as a DTE), 
then they may use a form of hardware handshaking: two control 
lines are crossed and the pins toggled with a logic “Hi” to indicate 
the DTEs are ready to communicate. If one DTE toggles its 
control pin “Lo”, communications are paused until the pin is 
again toggled “Hi”. The control lines usually link the RTS-CTS 
or DTR-DSR pins. In the case of the Mac and the Imagewriter, 
the handshaking lines are CTS-DTR. If the IMW needs to pause, 
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the “Hi” on its ОТВ pin goes “Lo”; the Mac detects this new 
condition on its CTS pin and stops sending data until its CTS pin 
is toggled “Hi” again. Got it? 

Another problem, anda further bastardization of the RS-232 
standard, occurs when two DTEs want to talk to each other using 
software (XON/XOFF) handshaking but have pins on their serial 
ports that are expecting hardware handshaking. This situation 
requires the old “fake-out” handshaking method. Pins that are 
normally “Hi” аге jumpered to the pins that expect a “Hi” before 
they willallow data transmission to begin. RS-232 cables for the 
IBM are notorious for this and require jumpering several pins to 
get the serial port to work. Usually, the normally “Hi” RTS pin 
is jumpered to the normally “Lo” CTS pin, while the normally 
“НІ” ОТК pin is jumpered to both DSR and CD. This “Ғаке-ош” 
method is very common in situations where multi-conductor 
cable is not available or where the exact method of hardware 
handshaking is not known. Allin all, the RS-232 standard has be- 
come a very unstandard standard. 

Anyway, enough sermonizing and on to some constuction 
details for the ultimate in Мас serial port 


CONNECTOR PINOUTS 


Мос ainiDIN Peripheral 08-25 
RS-422 я8-232 


ОТА 1% Output H/S OTA ta Terminal Ready (DTE output) 
CTS 2% input H/S CTS lear to Send (OTE input? 
T Tx Data TXD ansait Data (DTE output) 

| I 


fiac no longer uses PG Cinternally Jumpered to SG) 

Мас uses DTR/CTS hardwore i to Iru 

TXD* and RXD* used in 16-422 communications <App ietatk > 
RTS, ОСО and DSA not normally used by Mac 


xD- 
50 
AXD- 

XDe 
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switching... MACBOX!!! The first detail that needed to be 
resolved was the 8-pin miniDIN socket used by the newer Macs. 
The required plugs are impossible to find and wouldn’t work well 
panel mounted into a box. Since my Mac was an updated 512 
machine, I had a couple miniDIN to DB-9 adaptor cables that I 
extended to reach MacBox. Panel mount DB-9s are readily 
available, so I used two male DB-9s as inputs from the Mac and 
four female DB-9s as outputs to peripherals. Note when wiring 
the pins that they are numbered in opposite directions on the male 
and female connectors (I didn’t). The protective and signal 
grounds are now tied together within the Mac, soonly three wires 
are normally needed to connect serial devices. I included a 
handshaking line since it was wired that way in my modem cable 
and is needed for the IMW (the other devices handshake through 
software ХОМ/ХОЕЕ). 

Initially everything worked great until I decided to get the 
M100 to talk to the IMW. First of all, the M100 usually talks to 
printers through a parallel port. Thankfully, the built-in BASIC 
accesses the serial port. Also, I have SuperRom installed in my 
M100 which contains a word processor that accesses the serial 
port. So, another switch and a little more wiring later, I was soon 
printing away on the IMW from the M100...sort of. After about 
a page of data, everything would turn to garbage. Obviously I 
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was overloading the IMW's input buffer, no amount of toggling 
the IMW’s DTR pin was shutting off the M100 from continuing 
to send data. I soon discovered that while the handshaking pins 
were active on the M100, there was no firmware (ROM routines) 
to recognize hardware handshaking. About then Big Byte 
stepped in and handed me a set of golden tablets containing a 
М100 mod that would give the M100 adequate hardware hand- 
shaking. The mod details involved the piggybacking of a quad 
nand gate chip inside the M100 to use the DSR line to read the 
IMW's DTR line. To be more consistent to the Mac's way of 
doing things, I could have easily use the CTS line instead. (See 
references below) | 

Soon the M100-IMW connection was yakking away with no 
problems...except now the M100 wasn't talking to the Mac. I 
soon realized that I needed to run another wire from the Mac's 
DTR pin to the M100 DSR pin to "fake out" the M100 even 
though it was talking to the Mac using software handshaking. 
Tracing the wiring in the accompanying diagram should reveal 
the necessary connections. 

References: 
MacAccess, Hayden Books,1987 
Understanding Data Com., TI Library 
Imagewriter II Owner’ s Manual 
Portable 100 Magazine, 12/87 
Modern Electronics Magazine, 5/86 
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Resource Roundup 
Comments About PICTs 


Joel West is the author of the best selling MPW book titled 
Programming with Macintosh Programmer's Workshop. He is 
also the principle in Palomar Software, which produced the 
popular Colorizer DA and recently, the Pict Detective utility. In 
this column he continues his Resource Roundup with some expert 
insights into PICT resources. 


PICTS 


This month's focus will be on PICT resources, handles and 
documents. These QuickDraw pictures are the lingua franca of 
Macintosh graphics, the common ground between diverse appli- 
cations. 

As I’m always fond of emphasizing, software developers 
(yes, that means you!) must support compatibility and standards 
to keep the users and marketing types happy. Whatever other 
graphics formats you prefer, the standard user interface requires 
you to support PICTs in some form or another. 

Besides, РІСТ5 are the native format of QuickDraw, a mere 
transcription of the various QD calls. In practical terms, PICTs 
are what you get for free with your Macintosh graphics, so if you 
can display it on the screen, you can record it in a PICT. 

Now while I'm big on standards, I'm not so dogmatic as to 
ignore the reality that PICTs are often the lowest common 
denominator, such as when you're writing a complex PostScript- 
based program. Still, that doesn't mean you should ignore 
PICTs, or make them look like heck—since that's also what 
you'll get on the many non-PostScript printers. 


What kind are there? 


Our Mac world is divided into two classes of people: those 
own Macintosh II's, and the impoverished masses. (Before 
anyone starts flaming, let me say that I'm writing this with the SE 
on my desk at Palomar, and with my Plus at home, since other 
people are using my Mac II.) 

Anyway, there are the original, classic, ог“РІСТ-1” pictures 
that were defined with the Macintosh 128, and unchanged by the 
Plusand SE. Any Macintoshcan generate these and display them 


Joel West 

Palomar Software, Inc. 
MacTutor Contributing Editor 
MacTutor Vol. 4 No. 6 


Pascal 


accurately. 

The Macintosh II can also generate and display new, color, 
or “РІСТ-2” pictures that require Color QuickDraw. The main 
differences are that you get more than 8 colors, and you can have 
color bit images. 

Үои сап use a PICT-2 on a Plus or an SE, thanks to a clever 
DrawPicture() patch in System 4.1 and later. (See “Sleuthing the 
New System File" in the August 1987 edition of Resource 
Roundup.). The patch draws a PICT-1 approximation of the 
color picture. Unfortunately, in doing so, the patch throws all the 
interesting information on the floor. 

There is a reasonable way to preserve this information 
(Palomar would be glad to provide it to any developer upon 
request), but interest in doing this seems to be underwhelming. 
My conclusion is that we will have to live with this lobotimized 
approximation of PICT-2's for as long as applications must 
support machines without Color QuickDraw. (Three years? Five 
years?) [At the recent Developer Conference, MacTutor asked 
the Apple guru' s why Apple didn' t simply create one version of 
quickdraw for all machines so developers would not have to 
support multiple window, menu and PICT data structures. The 
answer was "Quickdraw requires the 68020" . Now I know that! 
But they could have written a 68000 version for the SE that 
allowed color quickdraw calls which defaulted to black and 
white, presenting to the developer a single programming model. 
It appears Apple intends to upgrade the SE to a 68020 and solve 
the problem that way. Incidently, there was some controversey 
over letting me ask that question, as the panel moderator said I 
was "Press" ,a dirty word at Apple, I guess. I would like to thank 
all the friends of MacTutor who hooted down the Apple represen: 
tative so I could ask my question. -Ed] 


Where do you find them? 


QuickDraw pictures are usually found in one of three places: 
е In a resource of type ‘PICT’; 
° In the clipboard; or 
° In the data fork of a file of type ‘PICT’. 

АП three usages can be found in a typical PICT-oriented 


Fig. 1 Our sample PICT object parsed with Pict Detective 
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application. Resources are created when the user copies a PICT 
into the Scrapbook; they're also used by applications that need to 
display aPICT in adialog, since one ofthe predefined dialog item 
types is a PICT resource. 

The other two formats are directly employed by users to 
interchange graphics between two programs. As documented 
with the Scrap Manager, the standard user interface requires all 
programs to be able to import a *PICT' clipboard entry, while all 
but the most brain-damaged of graphics programs can also open 
and save PICT files. 


How do you get one? 


Finding a PICT resource is criminally easy; depending on 
what you're up to, you're likely to try 


ph: PicHendle; 


ph := PicHandle( 
GetResource( ‘PICT’, resno)); 
FailNILCph); 


or maybe 


ph := PicHandle( 
Get lIndResource€ ‘PICT’, 1)); 


FailNILCph); 


(All examples shown here are in MPW Pascal, with a 
MacAppish flavor. I find myself re-implementing functions like 
FailOSErr and FailNIL for my non-MacApp programs, just to 
keep consistent.) 

The clipboard is a pretty easy place to grab a picture, too: 


ph: PicHandle; 
Ten: LONGINT; 


ph := NewHandleC0); 
len := GetScrapCHandle(ph), 
‘PICT’, offset); 
IF len < 0 THEN 
BEGIN 
IF len = noTypeErr THEN 
(% there wasn’t one *) 
ELSE 
Ға1105Егг(05Егг(1еп2); 
EXITCThisRout ine); 


END; 


Reading a PICT from the data fork of a file is also child's 
play. Like most of Apple's early formats, the first 512 bytes are 
a header; for now, we ignore them, but if you really care, the 
format is described in Macintosh Technical Note $27, 
"MacDraw's PICT File Format and Comments." 

Anyway, this is all it takes to figure how long the picture is 
and read it into a new handle: 


Fail0SErr(GetE0FCdocrefno, filelen)); 
FailOSErrCSetFPosCdocrefno, 
fsFromStart, 512)); 


piclen :- filelen - 512; 
phand := NewPermHandleCpiclen); 


_ © The Definitive MacTutor, Vol. 4 


Fai INIL(phand); 


HLockCphand); 
FailOSErr(CFSReadCdocrefno, 

piclen, phand*)); 
HUn lock (phand); 


Of course, I’m oversimplifying—or, as Kurt Schmucker 
used to say in his courses, “I’m lying to you just a little.” This all 
assumes that you have lots of memory (always a bad assumption) 
and that every picture is small (even worse.) More on that in a 
minute. Suffice it to say that, if you have large pictures and not 
much memory, the above code will give up. 


What do you do with them? 


Each picture has one piece of useful information directly 
readable by any application: its bounding rectangle. This is read 
by the code 


erect := ph^^.picFrame; 


The original documentation also says there's a size in the 
picture (picSize), but that's a big lie, nota small one. Nowadays, 
there are lots of big pictures, those longer than the 32,767 limit 
of a signed 16-bit integer. For reliable results, you must get the 
size from some other means (if you don't have it already), such 
as from the Memory Manager: 


piclen := GetHandleSize(ph); 


Of course, there’s really only one good thing to do with a 
picture: draw it. This is probably the simplest thing you can do 
with a picture: 


DrewPictureCph2; 


(This is another little lie, since QuickDraw can fail and not 
tell you about it, particularly with a big picture, but finding out 
whether QuickDraw is failing is beyond the scope of this article.) 

Of course, you can also invert all the previous steps for 
finding a picture: create a new resource, write the PICT to the 
clipboard, or write it to the data fork. 

Creating a new resource is a matter of two calls, 


resid := Unique 1IDC‘PICT’); 
AddResource(ph, ‘PICT’, resid, ‘’); 
Ға1105Егг(КезЕггог); 


Writing it to the clipboerd is also pretty easy: 


Fail0SErr(ZeroScrap); 
HLock(ph); 
Fail0SErr(PutScrap(piclen, 

‘PICT’, ph*)); 
HUnlock(ph); 


Writing it to disk is also easy; just don’t forget to zero the 
512-byte header if you don’t have something interesting to put in 
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the header (a reasonable simplifying assumption). Shown below 
is also one of the ugliest ways to generate the zero'd header, but 
is included to keep the code easy to follow: 


FailOSErrCSetEOF Cdocref no, 
piclent512)); 
long := 0; 
FOR 1:=1 TO 128 DO 
FailOSErrCFSWriteCdocrefno, 
SIZEOFCLONGINT), 610п022; 


HLockCphand?; 
FailOSErrCFSWriteCdocrefno, 

piclen, phand*)); 
HUn lock Cphand); 


PICT Sleuthing 


Regular readers of Resource, Roundup will recall previous 
articles that talked about keyboard sleuthing, printer sleuthing, 
and system file sleuthing. 

Unfortunately, the format of pictures is so complicated that 
sleuthing an arbitrary picture a byte at a time is a very involved 
process. Just when I thought I had a handle on it, along came 
PICT-2, making it even worse. 

At one point, I’d hoped to finish my program by August 
1987, but that was not to be. Instead, a local Mac developer, 
Marshall Clow, finished up the work and made a product out of 
something that I'd started, so we could release PICT Detective to 
the world at January’s Expo in San Francisco. The response has 
been suprisingly strong for such a specialized tool—proof posi- 
tive how many developers are doing graphics development. 

PICT Detective™ is a set of utility programs for the MPW 
programs. It consists of three MPW tools: 

• DePict decompiles PICT resources and documents into 
Rez source form 

• PictFork moves a PICT from a resource to a PICT docu- 
ment, or vice versa. 

e ShowPict puts up a modal dialog to allow you to peek at 
the PICT while within MPW. 

In addition, Pict.r contains enough declarations to be able to 
recompile any DePict'd data back toa picture. An earlier version 
was included in Chapter 9 of Programming with Macintosh 
Programmer’ s Workshop, but it has two severe limitations: it 
fails badly with bitmaps, and it doesn’t support the PICT-2 
format. 

You can also fiddle with the source before recompiling, or 
define new pictures completely from scratch using the Rez 
source form. Of course, Rez only compiles to the resource fork, 
but PictFork will move the compiled picture back to the data fork. 

For the duration of this article, I'll be illustrating the contents 
of PICTs using the DePict format, the only form I know of today 
for describing pictures. 

To give you some idea of what the output can look like, first 
take a look at the picture shown in Figure 1, which was created 
using SuperPaint. Now look at is its description of a simple 
picture in DePict form: 
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resource ‘PICT’ (0, purgeable) ( 
194, /* Actual length: 194 */ 
(0, 0, 120, 516), 
(  Version( 1); 
ShortComment( picDwgBeg ); 
ClipRgn{ 10, (Ø, Ø, 728, 576), 


PnPat( %”88 00 22 00 88 00 22 00"); 
0у5іге( (18, 18)); 
PaintRRect( (57, 40, 133, 425)); 
PnSize( (4, 4)); 
PnPat( $4FF FF FF FF FF FF FF ҒҒ”); 
FrameSameRRect{ ); 
LongComment ( picTextBegin( 
6, 0, 0, 2, 0x00)); 
LongComment ( picTextCenter ( 
@xFFF40000, 0х00608000)); 
ShortComment ( picStringBegin ); 
TxFont( times); 
TxSize( 48); 
DHOVText( -120, 102, "MacTutor"); 
ShortComment ( picStringEnd ); 
ShortComment ( picTextEnd ); 
LongComment ( picTextBegin( 
6, 0, 0, 2, 0х00)); 
LongComnent ( picTextCenter ( 
OxFFFCO000, 0х00628000)); 
ShortComment ( picStringBegin ); 
TxSize( 13); 
LongText( (116, 134), 
*The Macintosh Programming Journal^); 
ShortComment ( picStringEnd ); 
ShortComment ( picTextEnd ); 
ShortComment ( picDwgEnd ); 
EndOfPicture( ) 
) 
); 


Note that the length shown is the 16-bit picSize length, while 
the “actual length" is the length of the resource—usually the 
same for resources less than 32K long. 

Otherwise, if you know QuickDraw, the description is 
nearly self-explanatory. About the only opcodes that might not 
be familiar are ShortComment and LongComment, which brings 
us to... 


PICT Comments 


Lots of the interesting stuff in a picture won't fit in 
QuickDraw's mindset. Some of this stuff doesn't belong in 
QuickDraw, other probably did belong, but didn't make it in 
time. 

But there is a portable way for applications to share meta- 
information with other code: via picture comments. These are 
portions of a picture that are recorded and replayed by Quick- 
Draw, but, by default, have no effect on the displayed image. 

Picture comments have three principal uses: 

e To convey additional information that is useful for an 
application that is reading a picture previously saved to the 
clipboard or a document. An example of this is grouping 
objects, alá MacDraw. 

“ To communicate information from an application to the 
current printer driver. An example of this is including 
PostScript output for the LaserWriter. 
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* То get around some implementation limitation in Quick- 
Draw. This was particularly severe with the stack-based 
algorithms of the 64K ROM (which worked around the puny 
heap of a 128K Mac, but prone to stack overflow), but still 
required for large bit images. 

Of course, there's an overlap between these categories. 
Printer drivers can ignore some of the comments, but applica- 
tions typically generate (and must recognize) all three categories. 

Table 1 shows a list of the most common and important 
picture comments. Again, the names are those used by DePict; 
the main difference is that any comment that didn't start with pic 
had it added as a prefix, for consistency's sake and to make iteasy 
to distinguish picture comments from opcodes. 


Banding Bits 


When you draw a bit image on the screen with CopyBits(), 
QuickDraw uses roughly the same amount of memory as your 
bitmap (or pixmap) as a temporary scratch memory. This is 
sometimes too much for your Mac to tolerate. 

Clever programs break larger bit images into a series of 
horizontal bands, as illustrated by Figure 2. Each band is drawn 
with a separate CopyBits(), one below another, until the entire 
image is covered. | 


4— 640 pixels --------Ф 


50 scan lines 


480 
pixels 


50 scan lines 


50 scan lines Nine bands are 


32,000 bytes 
_ U Tenth band is 
50 scan lines 19,200 bytes 


30 scan lines 


Macintosh Il screen PixMap (640x480x256 colors) 


Fig. 2 PixMap 


The picBitBeg and picBitEnd comments indicate to an 
aware application that the intervening bits are bands of a single 
image, not separate images. Your code looks something like: 


PicComment(picBitBeg, 0, NIL); 
FOR i := 1 TO nbands DO 
BEGIN 


CopuBitsC...); 
; 


PicComment(picBitEnd, 0, NIL); 
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This is one case where an application must understand an 
input picture comment. Otherwise, your user will see a series of 
separate images from any program thatis kind enough to band the 
data into reasonable-size pieces. 

At Palomar, we live by the gospel we preach. When it came 
time to do the Colorizer package for the Mac II, we made sure that 
the Color SaveScreen™ screen dump FKEY outputs bands. The 
Colorizer application recognizes a series of bands between 
picBitBeg and picBitEnd as being a single bitmap object. 

How small should thou makest thine bands? Once upon a 
time, in the days of olden ROM, very tiny 3.5K bands were 
recommended. Thou must forsake this ancient ritual, since thou 
shalt fail miserably with the images of Color QuickDraw, which 
art 300K or more. 

As long as you're stick with a Macintosh Plus or later, a size 
of 20K-40K seems about right, according to Apple technoid, and 
MacTutor Founding Board Member, Chris Derossi, who's re- 
searched the subject. Some people like 32,768 (or slightly less). 
I happen to insist on a minimum of 21,888, so that a standard- 
screen Plus or SE screen dump is never banded. 

Note that the sizes measure the size of the bit image in 
memory, or height*width*depth /8. The actual size in the picture 
will be somewhat less, due to the PackBits compression per- 
formed by QuickDraw when recording the picture. 

Realize that the larger the band size, the more temporary 
memory will be necessary to display your picture. On the other 
hand, the smallerthe band size, the more bands you have; because 
each band has a fixed overhead, this can increase the size of your 
picture. For example, a 256-color PixMap has an overhead of 
about 1,100 bytes for each band; if memory serves me, Chris 
Derossi was able to save about 30K out of a 300K image by 
increasing the 20K bands to 40K. 


Whoa, Trigger! 


While we're on the subject of bits, I'd also like to remark on 
a truly under-documented picture comment, picLasso. How did 
the original MacPaint tell the difference between a bitmap 
selected with the rectangular selection tool and one selected with 
the lasso? (The tools shown below.) 


— 
Selection 
rectangle 
With a picture comment, of course. This same picture 
comment is also used by HyperCard and SuperPaint, and proba- 
bly some other applications I don't know about. 
I went ahead and selected a small image in SuperPaint and 
put it into the Scrapbook. This is what it looked like in DePict 
form: 


Lasso 


resource ‘PICT’ (-32766, purgeable) ( 
93, /* Actual length: 93 */ 
(2, 0, 14, 16), 
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(  Version( 1); 
ShortComment ( picDwgBeg ); 
ShortComment ( picBitBeg ); 
ClipRgn( 10, (0, Ø, 120, 576), %”); 
BitsRect( 


2, 
(0, 0, 14, 16), 
(0, 0, 14, 16), 
(0, 0, 14, 16), 
srcor, 
$°93F8" 
$” 1006" 
$^2001" 
$"4001" 
$^8001" 
$8006" 
$8038" 
$27150" 
$^CE00" 
$^A800" 
$^1000" 
$» 1000" 
$” 1000" 
$2000" 


); 
ShortComment( picBitEnd ); 
ShortComment( picDwgEnd ); 
EndOfPicture ( 


) 
); 
Now, if the same image is lasso'd, there is one main 


difference. The first few opcodes include the picLasso comment, 
as in: 


Version( 1); 

ers ian EL picDwoBeg ); 
ShortComment ( picLesso ); 
ShortComment ( picBitBeg }; 

ClipRgn( 10, (0, 0, 120, 576), %”); 
BitsRect( /* etc. etc. */ 


Tallying Text 


When you're including text in a drawing, a group of com- 
ments allow you to both exchange data with other applications 
and take full advantage of the high-resolution Laser Writer text 
placement. 

The picTextBegin comment allows including the following 
information: 

• Left, right, center or full justification 
• Rotation of text, 0-360? (although usually a multiple of 

90?) 

e Flipping coordinate system along horizontal or vertical 
axis 
e Single, 1.5 or double spacing 

This affects all the text objects up until the picTextEnd 
comment. The picTextCenter comment specifies the center of 
rotation for this group of text. 

If you want to see more code demonstrating these picture 
comments, look at “Editing Rotated Text" by John D. Olsen in 
the February 1988 issue of MacTutor. The picTextBegin com- 
mentis also important when it comes to talking about application 
compatibility with printer drivers. 
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Incidentally, the old ROM also required banding pieces of 
strings with picStringBegin and picStringEnd. On reading a 
commented PICT, you should strip out these archaic comments 
and reassemble into a single string. On output, don't bother to put 
them in. 


Pacifying MacDraw 


MacDraw has its own set of picture comments. Some of 
them are useful to other graphics programs, or to printer drivers; 
others are just odd MacDrawisms. 

The first such comment is picDwgBeg. Don’t ask me why, 
but MacDraw wants to see this comment. However, it must be the 
very thing you add to the picture, and it must be closed with 
picDwgEnd as the very last thing you put in the picture. For 
example, 


ph := OpenPicture(somerect) 
PicComment(picDwgBeg, 0, NIL); 


(* other drawing here ... *) 
PicComment(picDwgEnd, 0, NIL); 
ClosePicture; 


More useful information is contained in the grouping com- 
ments picDwgBeg and picDwgEnd, which bracket objects that 
have been grouped together to act like one object. This concept 
(and the associated comments) is useful for any graphics pro- 
gram, which is why we made it one of the few comments 
supported by the initial version of our Colorizer application. 

Other comments are related to arrowheads on lines. 
MacDraw provides arrowhead information in a PICT two ways. 
For itown use, it includes picture comments indicating what sort 
of arrowhead should be drawn on the beginning orend of the line, 
or both. For other programs, it includes a screen representation 
of the arrowheads, as in 


Shor tComment( picArrw! ); 

ClipRgn( 10, (Ø, Ø, 720, 540), $^"); 
Раїп{Агс{ (35, 288, 55, 308), 246, 48); 
Line( (45, 36), (45, 289)); 
ShortComment( picArrwEnd ); 


MacDraw II has fancier arrowheads, but I haven't laid my 
hands on a copy yet, so I can say how it represents those 
arrowheads in a PICT. 

Finally, MacDraw has a really wierd way of defining poly- 
gons. So wierd, in fact, that many third-party applications 
receive polygons from MacDraw and don't realize it. 

Instead of using QuickDraw polygon calls, MacDraw repre- 
sents all polygons by bracketing a series of line segments with 
picPolyBegin and picPolyEnd picture comments. А simple 
MacDraw polygon looks like: 


resource ‘PICT’ (0, purgeable) ( 
60, /* Actual length: 60 */ 
(0, 0, 720, 540), 
(  Version( 1); 
Shor tComment ( picDwgBeg ); 
ShortComment ( picPolyBegin ); 


© The Definitive MacTutor, Vol. 4 


ShortComment ( picPlyClo ); 
ClipRon( 10, (0, 0, 720, 540), 
Line( (27, 45), (135, 288)); 
ShortLineFrom( -126, 36); 
ShortLineFrom( -99, -63); 
ShortLineFrom( 0, -9); 
ShortLineFrom( -18, -72); 
ShortComment ( picPolyEnd ); 
ShortComment ( picDwgEnd ); 
EndOfPicture( ) 


$) 


Roll Your Own Comment 


Finally, there is a portable way to define your own picture 
comments and include information private to your application. 
You might want to do this when copying an image to the 
clipboard, if your application wanted to keep some information 
beyond the standard QuickDraw definition. 

As described in Macintosh Technical Note #181, “Every 
Picture [Comment] Tells Its Story,” the new picAppComment 
includes the application signature and a variable amount of data. 
Since every good developer registers his/her unique application 
signature with Macintosh Developer Technical Support, this 
means there will never be a conflict with other applications, 
right? 

I included an example of using this application-specific 
commentin the PICT Detective manual. To my knowledge, none 
of the software released as of this writing uses this comment, but 
such software will definitely be hitting the streets later in 1988. 


P.S. on PostScript 


In a future article, I'll talk a little more about how picture 
comments are used to communicate between an application and 
a printer driver. 

Many of the comments that are defined have to do with 
PostScript. Do you want to output direct PostScript to a printer? 
You have a lot of choices on how to throw it into a picture 
comment. 

However, one comment is so standard that even a cursory 
discussion of comments would be incomplete without it. 

The comment, picPostScriptHandle, is also one of the easi- 
esttouse: theremainder ofthe commentis nothing more than raw 
PostScript. When you see it in DePict output, the name seems a 
little odd, but it makes sense when you see the code to generate 
it. 

To take an extremely trivial example, suppose you want to 
precede any of your custom PostScript with your own proprietary 
notice, defined by a string resource: 


resource 'STR ' (1024) ( 
"%Copyright 1988 FooBar Software"); 


To add this to your PostScript output, you merely need the 
e: 


hand: Handle; 
Siz: LONGINT; 
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hand :- HendleCGetString( 10242); 
siz := GetHandleSizeChand); 
PicComment(picPostScr iptHandle, 


siz, hand); 


Later, you might take the picture file and disassemble it with 
DePict. The data would look something like: 


resource ‘PICT’ (0, purgeable) ( 
4062, 
(0, 0, 342, 512), 
(  Version( 1); 
ClipRgn( 10, (0, Ø, 342, 512), 
$^», 
LongComment ( 
picPostScr iptHandle( 
*SCopyright 1988 FooBar Software")); 


Finding PICT Comments 


As noted before, analyzing a picture a byte at a time is very 
complicated and requires that you build a complete parser similar 
to Apple's. 

The simple way is to let QuickDraw do the parsing for you, 
and then have your own code called just for what you want to look 
at. 

АП you have to do is install your own commentProc in the 
bottleneck procs, as in: 


адр := NewPtr(SIZEOF(QDProcs)); 
SetStdProcsCqdp*^); 

(* set default values *) 
qdp^.commentProc :- @MyComment; 

(Ж install our interpreting routine *) 


grafPort*.grafProcs := дар; 


The calling sequence for your comment-interpreting proc is 
the same as for the StdComment procedure: 


PROCEDURE MyCommentCk ind, 
dataSize: INTEGER; 
dateHandle: Hendle); 
BEGIN 
CASE kind OF 


END 
END; (MyComment) 


As you can see, this is just the inverse of the PicComment() 
call, with each of the parameters having the same significance. 

While you're writing your own comment-reading routine, 
you might as well include the call 


StdComment(kind, dataSize, dataHandle); 


at the end of your code, just in case. You have no way of 
knowing whatelse has been installed there, but it’s possible some 
future system software might patch this to catch the sorts of 
things currently not supported by QuickDraw pictures. 

The same process of installing your code in grafProcs is also 
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used if you must display or record larger pictures than сап be 
stored in memory at one time. The getPicProc and putPicProc 
fields redefine what's done by DrawPicture() and OpenPicture(), 
respectively. The correct use of spooling pictures like this is left 
for another time. 


Conclusion 


PICT resources are the standard format for Macintosh 
graphics, and, as such, QuickDraw provides tools that make it 
easier for your application to use PICTs. 

The PICT format can also be expanded beyond 
QuickDraw's definition via the use of picture comments. These 
can be used for portably exchanging data between applications, 
or for storing information specific to a particular application. 

If you want to know more about picture comments, see: 

е Macintosh Technical Note #27 (mentioned above) 
е Macintosh Technical Note #91, "Optimizing for the 

LaserWriter—Picture Comments" 

е Macintosh Technical Note #181 (mentioned above) 
е LaserWriter Reference (АРПА, 1987) 


[At the printing session of the Developer Conference, Apple 
reps made the strange comment that they wished the PicCom- 
ment would go away. Yet they had no alternative in mind to how 
Quickdraw limitations could be circumvented without PicCom- 
ments. They also denied any interest in Display Postscript. 
Finally, they had no comment on any future Apple enhancements 
for Quickdraw that would provide an alternative to PicCom- 
ments. The print gurus inside Apple seem to be saying we should 
all use normal quickdraw so Apple can continue it's printer 
independence myth, don't use PicComments, and forget that 
Quickdraw by itself is inadequate for today's sophisticated 
graphics requirements. We find this either a " head in the sand" 
attitude or Apple is working on something they don't want us to 
know about. Other Apple reps, when asked about this, said they 
may wish PicComments would go away, but they won' t because 
they are necessary and everything would break if they did. -Ed] 


Figure 1: Simple PICT 


Figure 2: Banded bits 
Figure 3: MacPaint selection tools 


Num Name Description 
100 picAppComment Application-specific comment 


130 picDwgBeg Beginning and end 
131 picDwgEnd of a MacDraw picture 


140 picGrpBeg Beginning and end 
141 picGrpEnd of grouped objects 


142 picBitBeg Beginning and end of 
143 picBitEnd a banded bitmap 


150 picTextBegin 
Specify text rotation 
151 pictTextEnd End of a text string 

154 picTextCenter Specify center of rotation 


Beginning of text string 


152 picStringBegin Beginning and end of 
153 picStringEnd a banded string (archaic) 


160 picPolyBegin Beginning and end of a 
161 picPolyEnd MacDraw-style polygon 


170 picArrwl Arrowhead on 2nd point of line 
171 picArrw2 Arrowhead on Ind point of line 
172 picArrw3 Arrowhead on both endpoints 
173 picArrwEnd End of arrowhead comment 


192 picPostScriptHandle PostScript picture comments 
12345  picLassoSelected bitmap is lasso'd 


Table 1: Application picture comments 
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Resource Roundup 
System S leuthing II: The Sequel 


About this time last year, I wrote an installment of Resource 
Roundup on the various changes in trap patches from System 3.2 
to 4.1, and the compatibility issues related to the use of those 
systems ("Sleuthing the New System File," August 1987.) 

That article seemed to have struck a chord, with many 
programmers (including some generous folks from Apple) tell- 
ing me it was extremely valuable to have the information all 
pulled together all in one place. 

Since that time, the original story has continued where we 
left off last time, with two new system software releases intro- 
duced to date. 

So, like many Hollywood writers and producers lacking 
creativity, I’ve decided to go for the easy buck, the cheap knock- 
off; in short, a sequel: 


Sleuthing the System File,Part II: MultiFinder. 
Starring System 4.2 (née 5.0) and 6.0. 
Written by yours truly. 
Produced by Apple Computer, Inc. 


Incidentally, we'll pick up the story where we left off last 
time, so if you have the earlier article handy, you may wish to 
grab it to refresh your memory. 


A Number of Numbers 

First, let me clear up a little appelative confusion in these 
most recent systems. 

I have two sets of disks sitting next to my desk. One is 
marked 5.0, dated October 1987; another is marked 6.0, dated 
April 1988. However, 5.0 is not called 5.0 by most of its 
components, although 6.0 is much better in this regards. 

If you'll recall our last episode, the naming scheme is 
somewhat arcane for the System and Finder (and now MultiFin- 
der). Table 1 shows an updated list of software versions, and the 
systems with which they are compatible. 

Release 5.0 actually consists of System 4.2, Finder 6.0 and 
MultiFinder 1.0 (figure that one out!). However, Release 6.0 
offers an important step towards sanity, with version numbers 
6.0, 6.1, and 6.0, respectively. It seems apparent that all the 
numbers will eventually be the same. 

Let's hope they stop changing the leading digit every 6 
months, or we'll be up to version 19.0 (instead of 9.3) in no time 
atall. Ialso like a two-part rule-of-thumb I've heard for software 
versions that is not specific to Apple's software: 1. When they 
change the first digit, the programmers were ambitiously adding 
new features, so watch out! 2. When they change the digit after 
the decimal point, you have a good, reliable piece of software, 
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because they were mostly fixing bugs, not adding them. 

Note that the table offers the most optimistic viewpoint of 
compatibility; if the version was ever considered compatible, I 
list it as compatible, although usually the latest version has the 
most up-to-date bug fixes. Also, a 512Ke with a 1 Mb or more 
(third party or otherwise) can be treated just like a Plus; other- 
wise, taking а 512К memory configuration beyond System 3.3 is 
not such a great idea. 

Not shown in the table is the great improvement in user- 
identifiable version information now included in all system 
Software. The 'vers' resource, when properly used by any 
programmer, provides the user with a way to unambiguously 
identify the version of software or a document. More on that 
another time. 

Passels of PC's 

A year ago, I was writing the earlier article on my Macintosh 
Plus; thus, my testing emphasized the Plus, because it was easier 
much more accessible. 

A full year later, I'm back to a Macintosh Plus again. 
However, this year I was able to test on Macintosh II and SE's 
owned by Palomar Software. 

Of the Mac II'satthe office, we have both the original ROM 
and the second revision (which provides 32-bit Slot Manager 
support). However, it should be noted that the ТСН’ resources 
don’t distinguish between the two, patching the same traps for 
each. Also, the location of all ROM-based traps were the same, 
lending credence to the speculation that the changes were limited 
in nature. 
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Any Similarity to Real 
Traps... 

As I’ve said before, Apple doesn't 
show me ROM listings, which, under 
trade secret law, allows me to write 
what little I know and publish it in 
MacTutor! 

Iusedthe same algorithm as in Part 
I, which compares the address of each 
trap to the standard unimplemented 
trap, $A89F. Тһе sample program 
shown there is unchanged. 

This gives me the availability of 
each trap by trap word ($A000-AFFF) 
with certainty, both for the traps that 
have names, and those that do not. But 
for the dispatched traps, I can't tell 
when (or which) new traps are added that share the same dispatch 
word. 

As before, I' ve left off those traps for which I have discerned 
names but are not supported by Apple. Even more traps are 
defined but not named outside Apple—although it's interesting 
to note that System 6.0 seems to remove many of these traps from 
the trap table, marking them as unimplemented. 

Apple does provide some clues as to why the changes were 
made, which were of great help. 


Official 
Date Name 
Jan 84 
May 84 
Apr 85 


Jan 86 
Jun 86 
12 Jen 87 
15 Jan 87 


14 Apr 87 
12 Oct 87 
30 Apr 88 


Bigger and Better 

Extensible software is one of my fetishes; my main com- 
plaints against the Mac OS and Toolbox design are in those areas 
where it is not extensible. 

Thus, in hindsight, I can say that the RAM-based trap 
patches introduced by Apple about two years ago were a brillant 
move. One look at the size of today's patches and the function- 
ality changes they provide will show how successful the concept 
has been. 

As we saw in the last episode, trap patches have three 
purposes. 

° Fix a bug; 

° Extend existing capabilities 

• Add a new trap. 

In System 4.2 and 6.0, very few new traps were defined. 
Instead, the most radical difference since 4.1 comes with Multi- 
Finder, which defines a few new traps and, more significantly, 
redefined many more. 

As before, the *PTCH' resources аге used to apply machine- 
specific trap patches. New are the ‘ptch’ resources, which define 
patches common to two or more machine types. This reduces the 
size of the System file by removing duplicate patches, although 
the actual memory used may be higher. 

In fact, the trend has been towards more and more memory 
allocated for patches. Table 2 lists the sizes of each patch 
resource, and the total size of the resources (approximately the 
total RAM required for the patches). 
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Table 1: System software versions 


Compatible with 


Finder MultiFinder 512 51Же Plus 


o 
o 


---. US 
-. 


0 
0 


OOV OI л сл сл Ol $ — — 
— © Ol A & С) — 


t Resource fork labels this *Finder 2.2” 


Table 1: Which System for Which Machine? 


As shown in Figure 1, the Macintosh II has increased the 
most. It once had the most up-to-date ROM, but with most of the 
patches in the other machines, plus those required for Color 
QuickDraw, it now leads the way. 

Unlike our last episode, Apple now approves allowing the 
user to install a stripped System disk with only those patches 
needed for their particular machine. (I guess the problem of 
building a MultiFinder master disk gave this an added urgency.) 

If the user tries the stripped System on another model, an 
error alert is given at boot time and (s)he's told to go back to the 
drawing board. 

MultiFinder 

MultiFinder has a major effect on the run-time environment 
of an application, including the available traps. 

As shown in Table 3, MultiFinder defines two new traps. 
_WaitNextEvent is a, GetNextEvent designed for non-preemp- 
tive multitasking, while  OSDispatch is currently used only to 
get at MultiFinder temporary memory management routines. 

Even without MultiFinder, _WaitNextEvent is imple- 
mented in System 6.0. If you wondered why Apple advised you 
to check the availability of the two traps separately, wonder no 
more. 

MultiFinder also patches a large number of traps to augment 
windowing, event, file control and memory-related functions. 
Changes also affect the Standard File Package and several 
Resource Manager calls, as shown in Table 4. 


Other New Traps since 4.1 

The new traps have been defined since the earlier episode are 
listed in Table 5. Allbutone of the traps are new with System 6.0. 

One new trap, LwrString, is a complement to the long- 
standing _UprString in the OS Utilities. It should be used only 
as a quick&dirty way to lower-case Roman text; a more portable 
call is to use the Script Manager transliteration routines. 

АП machines get a new manager in System 6.0, the Notifi- 
cation Manager. This providesa structured way for a background 
application to get a user's attention, as PrintMonitor does under 
MultiFinder. 
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The Notification Manager requires two new traps, NMIn- 
stall and NMRemove, which add and delete notification re- 
quests from a system-maintained queue. Everything you ever 
wanted to know about the Notification Manager is in Macintosh 
Technical Note #184. 

The Notification Manager traps are stored ‘ptch’ #2. 

Two traps that are not new to most programmers are 
—Debugger and, DebugStr. However, they are now provided by 
default by System 6.0, even if no debugger is installed. 

I think this is great. Suppose you accidentally leave debug- 
ging code in your program and give it to an unsophisticated user. 
Your debugging calls become no-ops instead of ID=12 bombs: 
which do you think the user would prefer? 

Finally, System 4.2 introduced one new trap for the Macin- 
tosh П only. The Pallette Manager was extended by _CopyPal- 
ette, for making a copy of a palette. 


RAM-based traps 

Although the Macintosh II included a new Sound Manager, 
this was not available across all machines. System 6.0 remedies 
this situation by providing the same RAM-based Sound Manager 
for all three machines. This provides bug fixes to the earlier 
version in the Mac II ROM. 

The Sound Manager patches for all three machines are 
stored in ‘ptch’ #3. 

Extended TextEdit, originally in RAM for the Mac Plus 
only, has been corrected and improved since System 4.2. Again, 
for all three machines, the manager is RAM-based, even though 
the Mac II has earlier versions in ROM. 

These TextEdit patches are stored in ‘ptch’ #0. 


Mac ІІ Teething Pains 

New babies have teething pains; the Macintosh II was no 
exceptions. 

Itappears that a large amount of new code was written for the 
Mac II ROM. Even for existing traps, some may have been 
recoded in 68020 for speed; other code was required to support 
many of the Toolbox extensions, such as auxillary window 
records. 

We all know there were severe time constraints in getting it 
out the door, so it’s not suprising there were problems, although 
I never noticed fatal problems associated with using my Mac II 
(except brain-damaged code incompatible with a 68020). 

Both System 4.2 and 6.0 include a large number of traps 
patched only for the Macintosh II. These are listed in Table 8 and 
9. 

System 6.0 includes a much more robust and aggressive 
Palette Manager than was included in System 4.1, where it was 
a last-minute addition. However, the Palette Manager is not 
shown in the list of trap patches, because it has always been 
RAM-based, so the current testing methodology will not show 
any changes. However, changes to the two Color Manager calls 
_SaveEntries and _RestoreEntries are a tip-off to this color re- 
write. 

I should also note that a few of these routines may also have 
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been patched to fix problems in the Macintosh Plus and SE. As 
noted, these routines were already patched in System 4.1 to 
provide new functionality (notably hierarchical menus), so I 
couldn’t tell if they also had been changed by 4.2 or 6.0. 


Other Bug Fixes 

The remaining trap patches are shown in Table 10. 

System 4.2 fixes the notorious early bug with ADBRelnit, 
while updating the _KeyTrans implementation. 

System 6.0 improves the behavior of the standard polygon- 
drawing calls with large coordinates. Even if only a few points 
were defined, large enough coordinates would crash QuickDraw 
(without warning). | 

This was first pointed out to me by Jean-Paul Harmand at the 
Paris developer's conference in April. His program is shown in 
Example 1; it works fine with 6.0, but crashes with ID=25 on 
System 4.2. 

There were quite a few places were traps were unpatched by 
one of the new releases. Since I haven't the foggiest idea of how 
to explain anything like that, I didn't list them, except for those 
traps patched in System 4.2 but not in 6.0. 


Hidden Changes 

I can't tell directly when a trap patch changes: if it was 
previously patched, all I know is that it remained patched, not 
whether the patch is the same. 

In addition, for the dispatched traps, I can't tell which new 
traps are added that share the same dispatch word. 

There are two areas that surely changed but don't show up 
on the list. 

First, System 6.0 includes major changes to software related 
to internationalization. This includes the International Utilities 
and the Script Manager. A brief list of the new calls is given in 
Table 11. Except for the previously-mentioned _LwrString, all 
of these calls are part of a dispatched trap, either _Pack6 or 
_ScriptUtil, respectively; thus, there's no way of knowing 
they 're there, except from the documentaton. 

Secondly, SysEnvirons has been updated for each machine 
and system version. Needless to say, this will always be aRAM- 
based call. 

Printing Glue 

In the earlier episode, I spent some time on the trap-based 
Printing Manager introduced in System 3.3. 

Programmers who can verify (or count on) System 3.3 or 
later should use the traps, since this is the official, supported way 
from now on. 

However, MPW programmers who still use glue may be in 
for а suprise. In MPW 2.0, the C and Pascal glue libraries first 
check for the trap to be implemented; if it is, they call it instead 
of performing the original Lisa Pascal glue functionality. 


Acknowledgements 
Since System 4.1, Apple has been including valuable release 
notes with each mailing of the new disks to developers. 
The release notes only keep getting better; in the case of 6.0, 
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it even includes a list of all the managers, any changes and their 
current known bugs. 

I'm sure I speak for all developers when I say the more 
timely information like this, the better. This information was 
extremely valuable, both in tracking down our own compatibility 
problems, and in preparing this article. 

If you haven't figured it out already, you should grab all the 
release notes in your possession, shove them into a binder and file 
itnext to/nside Macintosh and your tech notes in the programmer 
library. 

Tech Support also provided me with an early draft of the 
Script Manager 2.0 documentation. I was about to sit down and 
write a two-part series on internationalizing software until I 
heard about 2.0, so I've held it up until I can fully grasp all the 
information. Look for it in a future issue. 


Corrections 

This all started when I was writing Programming with 
Macintosh Programmer’ s Workshop . If you want a list of all the 
traps up to System 4.1, see Appendix E, but please excuse some 
of the formatting problems. 

In the prior episode, I said the Levco Prodigy (for the Mac 
Plus) patched certain unnamed traps. Duane Maxwell of Levco 
promised that he hadn't, but this information didn't make it into 
the earlier article in time for publication. 


Table 2: Trap patch sizes 


System 4.1 System 4.2 System 6.0 


Common patches 
'PTCH' #0 540 638 826 
ріст #0 10,214 
'ptch' #1 (Plus,SE) 4,762 
'ptch' #2 3,474 
‘ptch’ #3 3,866 
Subtotal 540 638 23,142 
Macintosh Plus 
‘РТСН’ #117 26,884 27,916 18,080 
Total 27,424 28,554 41,222 
Macintosh SE 
‘PTCH’ #630 12,958 15,622 15,712 
Total 13,498 16,260 38,854 
Macintosh Il 
‘PTCH’ #376 12,004 18,724 33,136 
Total 12,544 19,362 51,516 


Table 3: New traps In MultiFinder 


Name Word 50 6.0 #£MultiFinder 
_WaitNextEvent А860 ° ° 
_OSDispatch А88Ғ ° 
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Table 4: Traps patched by MultiFinder 6.0 
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Name Word 
. Open A000 
_Close A001 
. GetVolInfo A007 
. ReallocHandle A027 
. SetTrapAddress A047 
_HNoPurge А04А 
. RDrvrInstall A04F 
_NewHandle A122 
_HFSDispatch A260 
_SetCursor A851 
. CalcVis A909 
. CalcVBehind A90A 
. ClipAbove А90В 
. PaintOne A90C 
. PaintBehind A90D 
_NewWindow A913 
_SelectWindow A91F 
_BringToFront A920 
_Drag Window A925 
_Close Window A92D 
_AddResMenu A94D 
_GetNextEvent A970 
_EventAvail A971 
_WaitMouseUp A977 
_ModalDialog A991 
_UpdateResFile A999 
_GetNamedResource А9А1 
_SizeRsrc А9А5 
. GetResAttrs A9A6 
. GetResInfo A9AS8 
_SystemEvent A9B2 
_SystemClick A9B3 
_OpenDeskAcc A9B6 
_SysEdit A9C2 
_SysError A9C9 
. Pack3 A9EA 
Table 5: Other New Traps 
Manager Trap Word Version Machine 
Script _LwrString А056 60 Plus, SE, II 
Notification _NMinstall АОБЕ 6.0 Plus, SE, II 
Notification ММНетоу/е A05F 6.0 Plus, SE, Il 
Debugger ` Debugger A9FF 640 Plus, SE, |! 
Palette _CopyPalette ААА1 42 | 
DebugStr ^ | Debugger ABFF 640 Plus, SE, II 
Table 6: RAM-based Sound Manager 
Name Word 
_SndDisposeChannel A801 


_SndAddModifier 
_SndDoCommand 
_SndDolImmediate 


_SndPlay 
_SndControl 


_SndNewChannel 


_SysBeep 


ROM.-based Sound Manager traps are available in the Macin- 
tosh II only. With System 6.0, RAM-based traps are defined for 
the Macintosh Plus, SE, and II. System 6.0 also patches the OS 
Utility SysBeep is patched for the Macintosh Plus and Macin- 


tosh SE only. 


Table 7: RAM-based TextEdit 


Name 
_TESelView 
_TEAutoView 
_TEGetOffset 
_TEDispatch 
_TEStyleNew 
_TEGetText 
_TEInit 
_TEDispose 

_ TextBox 
_TESetText 
_TECalText 
_TESetSelect 
_TENew 
_TEUpdate 
_TEClick 
_TECopy 
_TECut 
_TEDelete 
_TEActivate 
_TEDeactivate 
_TEIdle 
_TEPaste 
_TEKey 
_TEScroll 
_TEInsert 
_TESetJust 


A802 
A803 
A804 
A805 
A806 
A807 


А9С8 


Word 
А811 


Table 8: Macintosh И System 4.2 patches 


Name 
Open 
_GetHandleSize 


_SwapMMUMode 


_GetMaskTable 
_FixDiv 
_NewRgn 
_MapRect 
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_PaintOne 
_PaintBehind 
_NewWindow 
_CouldDialog 
_FreeDialog 
_DiposDialog 
_CouldAlert 
_FreeAlert 


_DetachResource 


_HandToHand 
_DisposPixPat 


_DisposCCursor 


_SetWinColor 
_GetAuxWin 
_NewCWindow 


_GetNewCWindow 


_DrawPicturet 
 InsertMenut 


. CalcMenuSizet 


. CountMItemst 
. DelMenultemt 


f Patched in System 4.1 and later for the Macintosh Plus and SE. 


Table 9: Macintosh ІІ System 6.0 patches 


Name 
_DisposHandle 
_HSetState 
_SetOS Default 
_InitGraf 
_InitWindows 
_GetKeys 
_NewPixPat 
_SetDeskCPat 
_SaveEntries 
_RestoreEntries 


_EnablelItemt 
_MenuSelectt 
_MenuKeyt 


Word 
A023 


Т Patched in System 4.1 and later for the Macintosh Plus and SE. 


Name 
. UnmountVol 


_GetVol 
—DisposPtr 

. HLock 

. HUnlock 
_InitApplZone 


Word 
АООЕ 


A014 
А01Е 
А029 
А02А 
А02С 


Plus 
6.0 


ram 


Table 10: Other patches 


SE 
4.2 


4.2 
4.28 
4.28 
4.28 
4.2 
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 ADBRelnit 
. KeyTrans 


_StdPoly 
_PackBits 
_StdBits 
_StdTxMeas 
_MoveWindow 
_InitResources 
_SystemTask 


Legend: 


А07В - 4.2 4.2 
А9СЗ тат 42 4.2 


А8С5 6.0 6.0 тат 
АЗСЕ 6.0 4.2 

АЗЕВ 6.0 6.0 

ASED 60 6.0 

A91B 6.0 6.0 ram 
A995 6.0 6.0 6.0 
A9B4 6.0 6.0 6.0 


Build using: 


w. `. We We We 


CreateMake PolyTest PolyTest.a 
BuildProgram PolyTest 


Notation 41 42 6.0 
ROM ROM (КОМ 
ram RAM RAM RAM 
4.2 ROM RAM RAM 
4.28 ROM RAM ROM 
6.0 ROM ROM RAM 
- (n.a.) (n.a.) (n.a.) 


Print OFF 
Include ‘Traps.a’ 
; Include ‘ToolEqu.a’ 
Include ‘QuickEqu.a’ 
; Include ‘SysEqu.a’ 
Print ON 
QuickDraw RECORD , DECREMENT 
thePor t DS.L 1 
white DS.B 8 
black DS.B 8 
gray DS.B 8 
1tGray DS.B 8 
dkGray 0$.В 8 
arrow DS.B cursRec 
screenBits 


randSeed 


05.8 bitmapRec 
05.1 1 

ORG -grafSize 
ENDR 


Table 11: New Script Manager calls 


OS Utilities 
UprText 
LwrText 


Script Manager 
FindBlock 
Form2Str 
FormStr2Xx 
Form X2Str 
GetFormatOrder 
InitDateCache 
LineBreak 
LongDate2Secs 
LongSecs2Date 
PortionT ext 
ReadLocation 
Str2Form 
String2Date 
String2Time 
ToggleDate 
ValidDate 
VisibleLength 
WriteLocation 


Same as UprString 
Simplified change to lowercase 


Break Roman text from native run 
Display numeric format string 

Parse string to number using format 
Display number in string using format 
Arrange text for bi-directional format runs 
Initialize for String2Date and String2Time 
Break line on word boundary 

Convert date with era to 64-bit integer 
Convert 64-bit integer to date with era 
Proportionate justification information 
Read latitude, longitude, GMT difference 
Compile numeric format string 

Convert string to date 

Convert string to time 

Increase/decrease date field 

Validate date 


Length of text excluding trailing white space 


Write latitude, longitude, GMT difference 


International Utilities 


IULDateString 
IULTimeString 


Convert long date to string 
Convert long time to string 


Source Code Listing: Quickdraw Crasher 


; Sample program to crash QuickDrew with Polygon operation 


; Original by Jean-Peul Harmand 


; Trenscribed to MPW by Joel West for MecTutor, 6/10/88 
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MAIN 
PolyLen EQU $901E 


WITH QuickDraw 
PEA thePort 
_InitGraf 
_InitFonts 
_InitWindows 
_InitMenus 

CLR.L -(SP) 
-InitDialogs 
-TEInit 
-InitCursor 
MOVE.L #PoluLen, 
-NewHandle 


MOVE.L — A0,A2 
MOVE.L  CA02,A0 
LEA PolyValue 
MOVE .W 

61 MOVE.W (А12%,(А0 
ОВКА 00,01 


MOVE.L A2,-(SP) 


00 


s,Al 


tPolyLen/2,D0 


2% 


РЕА WhitePattern 


FillPoly 
-ExitToShe11 


WhitePattern 
DC.L 0,0 

PolyValues 
DC.WPolgLen 
DC.W $F020,$F0C3,$ 
DC .W $ 165С, $07EE 
DC. W $1170, $9284 
DC .W $O2FF, $0021 
DC.W $Е020, $FDC3 
DC .W$165C, $0 TEE 
ENDMAIN 


END 


165С,%07ЕЕ 
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Programmer's Tools 


Prototyper, MacExpress, and Facelt 


Compared 


Three Programming Tools Compared 


Introduction 

The purpose of this article is to review several programming 
tools that make the job of providing your application with a 
Macintosh? user-interface easier and quicker. While there are 
many different products of this nature, I can only reasonably 
discuss those products I have purchased and used. 

This review deals with products that are procedural in 
implementation. An alternative to these types of tools is the use 
of an object-oriented programming (OOP) library as a starting 
point for your application. OOP is especially attractive on the 
Macintosh because of the strong visual metaphor utilized by its 
interface, and I would encourage you to obtain as much informa- 
tion as possible if you are intrigued by OOP. 


Producing a Macintosh Application 

Since you probably spend a great deal of time using a 
Macintosh, you are no doubt familiar with the minimum require- 
ments of a good Macintosh application. Obviously, the user- 
interface is the characteristic that distinguishes Macintosh appli- 
cations from other computer programs. In general, your applica- 
tion should support the user-interface (as described by Apple) to 
the extent reasonable, including the clipboard, file operations, 
desk accessories, printing and support the latest system software. 

Implementing this type of interface is no small task. I would 
estimate that in a typical commercial application, as many as 
5000-10000 lines of code are dedicated to supporting the features 
described above. Many programmers turn, at least in part, to 
previously written libraries of code or commercial application 
shells to accomplish this task. 

This article discusses three products that address this need in 
varying degrees. The advantage of using these products is that 
they contain a great deal of “accumulated programming knowl- 
edge" related to implementing the Macintosh user interface and 
are excellent starting points for your application. 


Languages 

While the choice of a particular programming language is 
largely a function of which you are most comfortable with, some 
languages are better supported by programming tools than others 
and, in general, a compiled language is the best choice for a 
commercial application. 

Pascal probably has the largest selection of programming 
tools, but C, Assembly and Modula-2 (to namea few) are popular 
languages for the Macintosh that are supported by application 
"shells". Fortran, an excellent engineering language, is not 
supported by many programming tools. However, as you will 
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see, it is supported by at least one excellent product. 

Another issue that might affect your choice of a language 
and a programming tool is the level of support that they provide 
for the manipulation of resources. All good Macintosh program- 
mers make use of resources. The resource fork of an application 
should contain all of the internal text, pictures, menus and 
windows of your program. In this way, they are easily modified 
withoutre-compiling your code. I typically use ResEdit to create 
and edit resources and this program is available through APDA. 


Application Uniqueness versus "Shell" Support 

When attempting to select an programming tool, it is impor- 
tant to evaluate how much support you need. This decision is 
largely a matter of how unique your application is in terms of the 
"typical" Macintosh application and the amount of time and 
money you can afford to invest in “programming the interface”. 
Generally speaking, the more a programming tool or shell does, 
the less flexibility you have in implementing a truly unique 
application. I will call this characteristic the “support -vs- 
uniqueness tradeoff". Regardless of which tool you decide to 
purchase, it should provide (for whatever level of support it is 
designed to supply) functional capabilities as well as the ex- 
pected visual properties of a good interface to your application. 


A Trio of Hypothetical Applications 
If you compare the vast majority of Macintosh applications, 
they generally support the generation and editing of textual, 
pictorial or tabular data. While this is a gross simplification it will 
provide some framework for the discussion that follows. Let's 
consider three programmers (with only a minor knowledge of 
Macintosh programming): 


Programmer À is working on a complex engineering simu- 
lation that already exists on a mainframe. This program proc- 
esses text files as input and generates text files and graphics as 
output. 

Programmer B is working on a new application that is, 
essentially, an “iconic” programming language for educational 
purposes. 

Programmer C is working on a text adventure game that 
requires a few relatively simple dialogs but relies primarily on 
keyboard input in use. 


The characteristics of these applications are admittedly 
abbreviated in order to facilitate the discussion of the program- 
ming tools I will describe in this article. However, I think that 
they are representative of the types of programs an individual is 
likely to write. Mainstream software (e.g., word processors) are 
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so complex and well-supported in the market place that I think 
they are beyond the scope of this article. 
Three Programmer's "Scope-Out" Their Work... 

At this point, the three programmers introduced earlier are 
prepared to describe the general interface features needed by 
their programs. 

Since programmer A's application makes heavy use of text 
files, it would probably be appropriate for the application to 
generate the equivalent input files through dialogs and/or supply 
the program with Macintosh-style text editors for the user's 
convenience. Since the application also generates graphics, it 
must draw and print these pictures and ideally support the 
clipboard sufficiently to move both text and graphics to other 
applications for embellishment. Itis desirable (from a timeliness 
perspective) to use as much of the existing code as possible 
without sacrificing the valuable characteristics of the Macintosh 
interface (namely the concept of modeless operation). Program- 
mer A decides to implement the program in the following 
manner: 

The application will have one text editor which contains the 
input file for the simulation algorithm and its contents will be 
generated by the user's interaction with a dialog. To execute the 
simulation, the user selects a menu command and, when com- 
plete, the application will present its results in another text editor 
and a graphics window. At that point, the user can alter any 
parameters significant to the simulation by selecting a dialog or 
editing the text in the input editor and then “re-running” the 
simulation. The user can copy/paste the text and graphics 
associated with the application for further use in other programs. 


Programmer B's challenge is to support a very forgiving 
graphical programming environment. This application must not 
only display graphic information, but must understand the sig- 
nificance of the position and relationships of all the iconic 
symbols it supports. The application might support multiple 
“views” of its documents and allow the scrolling and splitting of 
document windows to allow the user to look at discontinuous 
portions of the same document. The program should support 
printing and have some special purpose dialogs for its various 
features. It should support the copying and pasting of compo- 
nents between documents and be able to save all of a document's 
contents to disk. Programmer B realizes that this application has 
many visual similarities with an object-oriented drawing pro- 
gram. This programmer decides to implement the program in the 
following manner: 

The application will have a “tool” palette of programming 
symbols and a "drawing" window. By double-clicking on an 
object created with one of these tools, the user may view and 
change any data associated with it. Since the application's 
purpose is to teach "structured-programming" the selection/ 
copy/paste of component(s) or module(s) is desired. 


The vast majority of Programmer C's work will be involved 
with the processing of keyboard input and generating the appro- 
priate responses. There are a few dialogs that allow the user to 
make selections among weapons or the like. Printing and 


676 


clipboard support are not really necessary but saving the state of 
a game is important so the programmer must support file opera- 
tions. Programmer C decides to implement the program in the 
following manner: 

The application will make use of a single text editor for the 
entry of commands or questions and the response the adventure 
game computes. There are also a few menu items that are tied to 
dialogs for the selection of “weapons” or actions to take at any 
particular moment in the "adventure". 


Introducing the Programming Tools 

Inthe following sections, I will introduce the three program- 
ming tools that I have purchased and used. I must preface my 
discussion with the following statement: Products of this nature 
are constantly being improved and enhanced, and, therefore, you 
should always contact the publisher concerning the features of 
the latest version of a particular package prior to making a 
purchasing decision. The three programming tools that I will 
discuss in this article fall into two general "categories": source 
code generation and pre-compiled libraries. Prototyper™ is ап 
application which generates resources and source code as output. 
MacExpress™ and Facelt™ are pre-compiled libraries of "inter- 
face" code. 

I will introduce these products in the order of their relative 
support for an application's interface. 


Prototyper 

Prototyper is an application that allows a programmer (or 
non-programmer) to "construct" an interface composed of 
menus, windows, dialogs and alerts in a “MacDraw™ - like" 
environment. The user can “link” buttons and menu items to 
windows, forming the essential structure of an application. 

The characteristic that sets Prototyper apart from other 
applications is that it can generate not only the resources associ- 
ated with the user-designed interface, but the Pascal source code 
(other languages will no doubt be supported in future versions) 
to implement this interface. This is the first commercial product, 
to my knowledge, that provides this capability. The significance 
of this is that the "interface designer" can create exactly the type 
of dialogs and windows that are appropriate for his or her 
application. 

This product could be very useful when the interface for a 
potential application is being coordinated with non-program- 
mers. It is easy to use, includes an example project, a thorough 
manual, and provides a good starting point for constructing the 
interface for your application. 


MacExpress 

MacExpress is a generic application that is best described as 
an application manager. It is composed of object files, interface 
files and a small file of "core" resources . It is available for 
several popular languages and compilers. The manual is top 
notch and includes several instructive flowcharts indicating the 
relationship between MacExpress' routines/data structures and 
your application. There are several excellent example programs 
on disk. MacExpress adheres closely to the Macintosh user- 
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interface guidelines, supports desk accessories, handles the main 
eventloop of your program, provides support for menus, handles 
the user's interaction with windows, supports the use of icons in 
a manner similar to the Finder, and provides assistance in 
creating "dialog" views. 

MacExpress, while being procedural in implementation, 
presents the programmer with a very “object-oriented” environ- 
ment where "objects" such as windows and icons are sent 
messages. The main event loop of your application resides in 
MacExpress where “raw” events are processed and translated 
into messages (you may pre-process these raw events for your 
own purposes). These messages are then handled by your own 
routines and/or passed on to the MacExpress module for process- 
ing. Programmers familiar with the technique of passing the 
address of routines in a procedure call will feel very much at 
home using this package. MacExpress is compact and extremely 
fast in use. 

In MacExpress, objects have standard routines associated 
with their functionality. These standard routines can be overrid- 
den and/or used in conjunction with your own routines. The 
essential idea is that, for instance, a window is sent a message 
("the mouse went down in my content region") and your appli- 
cation then responds appropriately via a *MouseDownProce- 
dure" or just calls the generic procedure to handle this event. 

The most attractive feature, in my opinion, of MacExpress 
is the sophisticated level of simplification it affords the program- 
mer increating windows. Windows may contain multiple panels 
all allowing resizing, splitting, scaling, scrolling, and au- 
toscrolling. In addition to this, all of the functionality of normal 
"document" windows can be given to dialog "views" and 
MacExpress similarly delivers “processed” events in the form of 
"messages" to these composite windows. 


Facelt 

Facelt is a series of stand-alone code resources that provide 
your application with an excellent user-interface. FaceItaccom- 
plishes this without linking and can be used by programs created 
with several languages. The manual is technical but complete 
and provides a thorough discussion of Facelt’s capabilities and 
how to access them. There are several documented example 
programs that demonstrate how to access the features of the 
product. Facelt is heavily resource oriented and, a file of “core” 
resources acts as a starting point for the resource fork of your 
application, in a manner similar to MacExpress. There is also an 
"interface" file that contains the declarative header needed to 
access Facelt’s data structures and a short routine to “jump” to 
Facelt’s code resources. 

Facelt is “one-step” beyond MacExpress in terms of the 
support it affords an application. The price for this support is a 
reduced ability to generate very unique applications. However, 
a program utilizing FaceIt immediately has access to many 
features which are extremely difficult to implement from 
"scratch". Facelt provides your application with text editors, a 
scrollable graphics window (with reduced view window), 
spreadsheet-type windows, complete printing support, high- 
level support for modal dialogs and alerts, support for back- 
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ground processing under MultiFinder™ , support for DAsand the 
clipboard, and various memory and resource manipulation utili- 
ties. 

In utilizing Facelt, your program will implement a main 
event loop that handles program specific “commands” while 
Facelt contains its own main event loop that directly processes 
"raw" events. At the beginning of your own program's “main 
event loop”, your program passes control to Facelt, and hence the 
user. Facelt intercepts events; handling “generic” events (like 
opening a text file into one of the text editors) and passes control 
to your program's main event loop when one of your “ргортат- 
specific" commands is requested. | 

Your program will access all of Facelt’s high-level interface 
utilities through a subroutine or procedure call. There are six 
(long integer) arguments involved in each call to Еасей. These 
six arguments are single or multiple *macro commands" with 
any obligatory parameters that represent some unique function- 
ality of FaceIt. Programmers new to the Macintosh will probably 
require little knowledge of the Macintosh ROM with the excep- 
tion of QuickDraw™ (for generating lots of neat graphics). 

Your program can create and/or access information in any of 
the windows, and it is very easy to implement complex dialogs 
with Facelt. Facelt handles the user's interaction with a dialog 
and provides very simple techniques for implementing scrollable 
lists, pop-up menus, and filter/activation-deactivation instruc- 
tions, etc. Facelt essentially reduces the task of implementing 
dialogs to that of simple string manipulation. 


Back to Our Programmers... 

Based upon the above discussions concerning the features 
and capabilities of each programming tool considered, I will now 
suggest which programming tool (among those covered in this 
article) would be appropriate for each programmer. 

Since programmer A is involved in the generation of a 
complex application that already exists on another computer, this 
programmer is primary concerned with the amount of time and 
complexity that would be involved in adding an appropriate 
interface to the program. The best choice for this application is 
Facelt. This package automatically provides text editors, a 
graphics window and “spreadsheet-like” windows all of which 
have “display options” that are user-configurable. 

Because of the amount of interactive graphical support 
required by programmer B's project, Еасей would not be a 
reasonable choice. The need for splitting and multiple views of 
the same document suggests that this programmer utilize 
MacExpress. This package would provide the most flexible 
“window environment” of any of the products discussed. Pro- 
grammer B must write the code associated with updating the 
contents of the windows, printing, any required text-editing, file 
operations and clipboard support. 

Although the application-specific complexity is by no 
means negligible for programmer C’s project, the interface is 
quite simple. It would probably be best for this programmer to 
write this program from scratch while utilizing Prototyper to 
initially formulate the code and resources necessary for the 
menus, windows, and dialogs. There are several sources for text 
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editor algorithms and these packages, in combination with Proto- 
typer, would probably be sufficient for programmer C's pur- 
poses. 


Relative Strengths and Weaknesses of the 
Programming Tools 
The products that I discuss in this article are, in my opinion, 
ideal for certain programming projects and not so ideal for others. 
The lack of certain features in a particular product does not 
necessarily represent a weakness or short-coming but might 
indicate a different philosophy concerning the proper "role" or 
level of functionality that these products should provide. With 
these comments in mind, I have compiled a brief summary of my 
opinions of each of the programming tools. 


Prototyper 

While Prototyper is not an application shell, it does have 
many features that make it ideal for the programmer new to the 
implementation of Macintosh dialogs, windows, alerts and 
menus. It is an excellent tool for the coordination of an interface 
*design" with non-programmers. Prototyper could be used to 
form the initial structure of your application's interface, be it 
large or small. Prototyper is also a very educational product with 
regards to the use of the toolbox in creating an interface. 


MacExpress 

MacExpress is a true generic application manager. It has 
been carefully structured to support the general concepts of an 
object-oriented program. It is small and very fast, and produces 
applications with an excellent interface. While you must write 
the code for printing, picture/text management, supporting the 
clipboard, file operations, and the integration of dialogs into your 
code, it is probably the most extensive shell that still provides the 
programmer with near complete freedom in the design of an 
application. 


Facelt 

Facelt is a series of stand-alone code resources that imple- 
menta full-fledged application. While the programmer is limited 
in terms of the level of unusual or highly unique features his or 
her application may have, Facelt provides complete support of 
printing, the clipboard, desk accessories and a very high level of 
support for background processing, picture/text handling and 
dialog management. Facelt is also one of the few application 
managers that supports Fortran and Basic. 


Example Program 

Since the purpose of this article is to describe programming 
tools and what they do for the programmer , I would be remiss if 
I did not include an example program. 

The purpose of a programming tool is to assist the program- 
mer in generating a good application by reducing the amount of 
time and the amount of code that he or she must write. As an 
example of what a well-designed programming tool can do to 
assist you in your efforts, I have included a listing and screen 
*snap-shot" of an example plotting application that utilizes 
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Facelt. This program makes use of Facelt’s “spreadsheet” and 
graphics windows. The example program (in Fortran) demon- 
strates the integration of Facelt into your application. 


program examp 
implicit none 


“type” declarations end initializations for program.. 


l Include FaceIt declarations.. 
l include StorMF . inc 


ILoad frequently used (but un- liked) subroutines into memory 
loed JumpMF 
load toolbx 


! Inform FaceIt of application? resource file Cif separate) 
name = ‘examp.Rsrc’ 


!Initialize FaceIt 
| -> enable auto-opening of TEXT and PICT files from Finder 
| -> set aside 50 Kbytes of space for stack expansion (for 
pictures) 
call FaceItC1,0,-1,50,0,2) 


IEnter your program's main event loop 

do 
Ipess control to FaceIt Cand hence the user) 
call FaceIt(0,0,0,0,0,0) 


Iprocess а program specific command.. 
select case(MAC) 
case( ‘About ^) 
Ithe user chose the “About Program..” menu item 
lopen the “About” alert (resource ID 1099) 
call FaceItC2,0pnA1t, 1099,0,0,0) 


case( ‘Open’ ) 
Ithe user chose the “Open? menu item for the 
spreadsheet window 
Ipresent the user with the standard file dialog 
Irestricting the files displayed to those of type 


MAC=’TEXT’ 
call FaceIt(0,Std0pn,0,0,0,0) 
if (nameO “Сәпсе1”) then 
lif the user didn’t press the “Cancel” button 


“TEXT” 


then... 


„read disk file 
assign numbers to the data array 
е assign column names to STR? resource 1001 
using 
FeceIt's SetStr utility.. 


endif 
Idisplay the array іп the spreadsheet window.. 
-әдіуе FaceIt a pointer to the array to be 
displayed 
| -)display the array in the spreadsheet window 
аггаур{г(1) = toolbxCPTR, dat) 
call FaceItC1,SetSh1,500, 10,0,5) 


case( 'Plot..^) 
| {Ре user chose the *Plot..^ menu item 


Itrensfer the information for this dialog to Facelt 
| -)trensfer dialog item list status 
do (i21, 16) 
dialog(i)=plotdialog(i) 
repeat 
! -»use list of column names (STR# 1001) in pop 
menus... 
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listIDC 1)= 1881 
115%10(2)= 1001 
! ->transfer textual information (text and 
numbers) to FaceIt 

| through the “name?” variable (used as an 
internal file) 

writeCname,30) 

title,naxY,divY,minY,minX,divX,maxX 


lopen the dialog (resource ID 2000) for manipula- 
tion by the user 
call FaceItC2,0pnD1g,2000,0,90,0) 


lafter the dialog has been dismissed, process it.. 
if K(dialogC 1221) then 
lif the user pressed the "ОК? button then.. 


transfer the (changed) information from FaceIt 
to the 
Іргодгап... 
!{гапзГег dialog item status back to program 
do (1=3, 16) 
plotdialog(id=dialogli) 
repeat 
Itrensfer textual information (text and num- 
bers) back to 
! program 
read(name,31) 
title,maxY,divY,minY, minX, divX, maxX 
!based upon the values of this info, prepare to 
plot 


.Set а few variables based upon info from 
dialog... 


Ibegin recording a QuickDrew picture (the plot) 
call FaceIt(0,NewPic,0,0,0,0) 


„draw the plot here.. 
„draw the axes... 
„plot the points.. 


lend the recording of the (plot) and display it.. 
call FaceItCQ,RetCt1,0,0,0,0) 
endif 


case default 
end select 
repeat 
30 format(A32,F20.6,14,F20.6,F20.6,14,F20.6) 
31 format(A32,F20.0,14,F20.0,F20.0,14,F20.0) 


епд 


The following screen “snap-shot” captures the example 
program after the user has loaded some data into the “spread- 
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sheet" window, produced one plot and is preparing to generate 
another. 

What might not be immediately obvious is the number of 
features that this very small application has as a result of utilizing 
Facelt. The user has access to “spreadsheet”, text editor and 
graphics windows with the expected scrolling, selection and 
editing characteristics. The application offers complete support 
for printing and the clipboard in all of the windows. This 
application also sports a functional and intuitive plot dialog that 
Icreated with ResEdit. This dialog is displayed with a single call 
to Facelt and features editable text items, pop-up menus and 
scroll bar controls (all of which are supported by Facelt). 

This small application is an excellent example of the value 
of programming tools or shells. These products have unique 
features specifically designed to reduce the burden of generating 
an application's user-interface, permitting the programmer to 
concentrate on the unique characteristics of his or her program 
and not become overwhelmed in the task of “programming the 
interface". 


Additional Programming Considerations 

After you have completed your application using any of 
these products, there are a few considerations you should take a 
look at concerning the use of the programs. I am referring 
specifically to disk space requirements and operating in a shared- 
application environment. 

Ideally, your program should take up as little disk storage as 
is reasonable and operate smoothly under MultiFinder. While 
Prototyper and MacExpress (V 1.14, new version appears to have 
utilities for working with MultiFinder ) do not address these 
issues, FaceIt has some unique features in these areas. 

Facelt is really a *stand-alone" product. There are essen- 
tially three "places" that Facelt can be located. It can be placed 
in the System Folder where it will be available to any program 
that uses it (without linking), it can be added to your program file 
to create a completely stand-alone application, or it can be added 
to the “System”, where it is available to all programs that use it 
and only one copy is loaded into memory under MultiFinder. 
Either of these techniques can be used to reduce the disk space 
and memory requirements of your product (which might consist 
of multiple applications). 


Making the Decision on a Programming Tool 

Any recommendations that I make to you should be consid- 
ered in light of my own programming experience. I am, for the 
most part, involved in large, technical programming projects. 
My programming time is spent in the details of implementing 
"engineering" concepts in code and, consequently, Ido nothave 
a great deal of time to devote to “programming the interface". In 
light of this information, here are my recommendations for the 
use of these programming tools: 

If youare receiving interface input for your application from 
non-programmers and require several unique interface features 
but not a substantial amount of application support (you are 
writing the code for the clipboard, printing, window updating, 
etc.), or you just want to know how the Mac interface in dialogs 
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and menus is implemented, get Prototyper. Prototyper is easy to 
use and has several truly unique features that could make it very 
valuable to many programmers. Prototyper supports the follow- 
ing compilers: LightSpeed™ Pascal, Turbo™ Pascal, TML™ 
Pascal and MPW™ Pascal. Future versions of this product will 
probably support the C language. [$125.00, SmethersBarnes, 
Р.О. Box 639, Portland OR, 97207, (503)-274-2800]. 

If your are developing a unique application in Pascal, C or 
Assembler and need speed, excellent window and application 
management, you are comfortable with writing the code for 
printing, file operations, clipboard and dialog support, then I 
would suggest you use MacExpress. This package is probably 
the best among those discussed in this article for creating a truly 
“unique” application. MacExpress supports the following 
compilers: MPW™ Pascal, MPW™ C, Consulair™ Mac C, 
TML™ Pascal, Aztec™ C, Lightspeed™ C, Lightspeed™ Pas- 
cal and various “Assemblers”. [$195.00, Alsoft™ Inc, P.O. Box 
927, Spring TX, 77383, (713)-353-4090]. 


If you are transferring an existing technical application 
(even in Fortran) or creating a new one and the amount of time 
and/or money required to “program the interface" is a critical 
issue, I would suggest using the programming package Facelt. 
This is a particularly good choice if you find reading Inside 
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Macintosh difficult. Integrating Facelt into your application 
requires few changes to existing code and minimizes “toolbox” 
calls. The price that you pay for this level of support is an inability 
to implement any unique or unusual interface features. This 
package is certainly the “quickest” way to add a Macintosh 
interface to a program. Facelt supports the following compilers: 
ZBasic™ , LightSpeed™ C, MPW™ C, Language Systems™ 
MPW Fortran, MacFortran™, Microsoft™ Fortran, Semper- 
Soft™ MPW Modula-2, Lightspeed Pascal, MPW™ Pascal, 
TML™ Pascal and Turbo™ Pascal. [ $50.00 (single compiler), 
$100.00 (10 compilers), FaceWare, 1310 N. Broadway, Urbana 
IL, 61801, (217)-328-5842). 


Closing Remarks 

I hope that this short article proves to be helpful to you in 
your evaluation of a programming tool. As I stated earlier, this 
article is a brief review of only three packages that are currently 
available. I encourage you to “shop-around” and obtain as much 
information as you can. Since a programming tool may, to a large 
extent, determine the quality of your application's interface, it is 
vital (to your application's success!) that you use the proper tool. 
Good Luck! 

22) 
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OS/2 Presentation Manager 


The Good, the Bad, and the Ugly: 
OS/2 Presentatlon Manager for Mac Programmers 
by Dan Weston 
Nerdworks, Portland, Oregon 

The Presentation Manager (PM) is Microsoft's and IBM's 
answer to the Macintosh user interface toolbox. Due out in late 
1988 with OS/2 version 1.1, PM provides a set of new operating 
system functions for application programmers that is somewhat 
similar to the functions supplied in the Macintosh ROM. OS/2 
programmers can access these functions to create windows and 
menus, use the mouse, and do all the things that Mac program- 
mers have been doing for over four years now. PM is directly 
descended from Microsoft Windows, so programmers familiar 
with Windows will have little trouble making the switch to PM, 
although their Windows application source code must be sub- 
stantially modified to work with PM. 

This article will attempt to explain the main features of PM 
in terms that Macintosh programmers should be familiar with. I 
know that many people in the Mac community look at OS/2 with 
deep suspicion, but even if you feel that way, read on, and you 
may find that there are things to appreciate in PM. 


Events and Messages 

The foundation of any Macintosh program is the event loop. 
The Macintosh operating system watches the outside world, 
including the mouse, keyboard, and disk drives, and signals the 
application whenever an event occurs. Macintosh programs are 
event driven. 

In a PM program, messages take the place of events. When 
‘mouse and keyboard events take place, PM tells the application 
by sending messages to it. Thisisconceptually very similar to the 
Macintosh event loop, but PM has a much richer set of messages 
and has made the message architecture more general and exten- 
sible so that itis very easy for applications to create new message 
types. 

Many of the messages have direct anologs in Mac event 
types, such as mouse button down and up messages (although 
there can be up to three mouse buttons), activation and update 
messages, and keyboard messages. Macintosh programmers 
familiar with event-driven application architecture will not find 
it too hard to make the adjustment to a message driven system. 


Windows 
The main components of a PM program are windows. The 
System provides many predefined window types, including 
frame windows, push buttons, radio buttons, menus, and title 
bars. The predefined window types are know as “window 
classes". Each window class defines an object that enclose a set 
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of functionality that is available to the programmer simply by 
sending messages to a window with that type. 

The messages in a PM system are actually sent to an 
application's windows rather than the application itself. Each 
window has an associated window procedure that receives 
messages from the system and other windows. For example, 
when the user presses the mouse button, the system sends a 
mouse button down message to the window that is underneath the 
mouse at the time of the event. The window then processes the 
mouse down message as it sees fit. Different types of windows 
respond differently. 

А standard PM window, with title bar, size border, and scroll 
bars, is actually made up of several different predefined window 
types. The most basic is the frame window. On top of the frame 
window sits the other windows, such as the title bar window and 
the scroll bar windows, that gives the window its distinctive look. 
The frame window "owns" the other windows, called control 
windows, that sit on top of it. The ownership relationship is 
important since it allows the control windows to communicate 
with the frame window. | 

For example, the title bar window class responds to a mouse 
down event by tracking the mouse and allowing the user to drag 
an outline of the frame window around the screen to position it, 
just like on the Mac. The way this works is that the title bar 
window handles all the tracking and the display of the window 
outline. When the mouse up message comes to the title bar 
window, the title bar window sends a message to the frame 
window telling it the new position on the screen. The frame 
window then sends messages to all the windows that it owns 
telling them to redraw themselves at the new position. 

Typically, a programmer writing a PM program creates at 
least one new window class to make a program. In the terminol- 
ору of PM, this is the "client window". А client window 
corresponds to the content area of a Macintosh window. The 
client window is also owned by the frame window. Its main 
responsibility is to display data for the user. So while frame 
windows and their constituent control windows behave the same 
in most programs, it is the client window which gives each 
application its visual personality. 

The operating system takes care of routing messages to the 
appropriate window. Ап application programmer never sees 
events that are handled by other windows. For example, when a 
normal Mac program gets a mouse down event, it must call 
FindWindow to determine what part of the window received the 
click and branch accordingly. In a PM program, the application 
programmer never sees a mouse down in the title bar or menus 
because those events are handled by the control windows at those 
locations. The application programmer only handles messages 
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directed to those windows he or she creates, such as the client 
window mentioned above. 


The Window Procedure 
Each window has an associated window procedure that 
processes all messages for that window. The syntax for a window 
procedure is consistent for all windows, so all messages are 
essentially function calls to the window procedure of the window 
receiving the message. A very simple window procedure is 
shown below. 


MRESULT MyWindowProcChwnd, msg, mp 1, mp2) 
HWND hwnd; 
USHORT msg; 
MPARAM mpi; 
oe mp2; 


HPS hps; 


ВЕСТ. rect; 


switch (msg) ( 

case WM_PAINT: 
hps = WinBeginPaintChwnd, NULL, &rect); 
WinFillRectChps, &rect, CLR_WHITE); 
WinEndPeintChps); 
return CMRESULT29L ; 

default: 
break; 


return WinDefWindowProcChwnd,msg,mp1,mp2); 
) 


The window procedure is normally a long switch statement 
that decodes the message and responds appropriately. А key 
feature is that the window procedure calls WinDefWin- 
dowProc, for all messages that it does not handle it. WinDefW- 
indowProc is the default window procedure supplied by the 
system. The default window procedure implements the default 
window behavior. Individual window classes handle only those 
window messages that they want to modify, passing the rest on 
to the system. This is a marvelous model for programmers 
because they can utilize all the default behavior without having 
to know how it works. 

The arguments to a window procedure always follow the 
syntax given above, but the contents change depending on the 
particular message. The arguments are summarized below: 

hwnd: a window handle to the window receiving the mes- 
sage. (Note: handle has a different meaning in PM than in the 
Mac. A PM handle is more like a token that the system knows 
how to use to find the window data structure.) 

msg: a 16 bit integer that identifies the message type. 

трі: a 32 bit value whose interpretation depends on the 
message type. 

mp2: a 32 bit value whose interpretation depends on the 
message type. 


Creating Window Subclasses 
Application programmers normally create their own win- 
dow class and supply a window procedure for that class. They 
must register the class and its associated window procedure with 
the system. Once registered, the window class can be used to 
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create multiple instances of windows of that class, all of which 
use the same window procedure. The window procedure created 
by an application for a new window class handles selected 
messages and passes the rest on to WinDefWindowProc to get 
the default behavior. This makes creating new classes very 
simple. 

Another way to create a new window class is to subclass an 
existing class, using its window procedure as the default instead 
of WinDefWinProc. For example, suppose you wanted a new 
Ше bar type that drew its contents in italics instead or regular 
text. You could create a new class based on the standard title bar 
window class by subclassing the title bar class. 

When you create a window subclass in PM, you get the 
address of the window procedure for the original, or parent, 
window class. You then construct a window procedure for the 
subclass that calls the parent's window procedure instead of 
WinDefWinProc. That way, all messages that your window 
procedure doesn't intercept are processed as they normally 
would be by the parent class. Going back to the example ofa title 
bar that used italics, it would only be necessary for the subclass's 
window procedure to respond to the WM, PAINT message by 
drawing the title bar as it saw fit. All other messages could be 
passed to the original title bar window procedure. You don't 
have to reinvent the title bar, just change those parts you want to 
change. 

Subclassing is a very elegant and simple way to extend or 
modify the behavior of the system. PM makes it easy to do. 


Window Updating 

Window drawing in the Mac environment is triggered by the 
update event. The Window Manager keeps track of the update 
region and generates an update event whenever a portion of the 
window needs to be redrawn. Smart Mac programmers utilize 
this mechanism by isolating all window drawing within the code 
that handles update events. In order to force a portion of the 
window to be redrawn, these programmers add that portion of the 
window to the update region and rely on the update event 
mechanism to call their drawing code. 

The PM drawing architecture is very similar. All windows 
have an update region. When the update region is not empty, the 
system sends a WM PAINT message to the window. АП 
windows should respond to a paint message by drawing them- 
selves. 

Your client window procedure should respond to a paint 
message by drawing a representation of the current state of the 
data associated with the window. For a word processor, you 
would draw the text and graphics of the document. 

Just like the Macintosh, PM clips all drawing in a window 
during the paint message so portions of the window which don't 
need to be redrawn are not touched by graphics operations. 

Mac programmers familiar with the update event mecha- 
nism on the Macintosh will have no problem adjusting to the PM 
method of painting windows. 


Menus 
Menus in PM are a special predefined window class that sit 
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on top of a frame window just like the title bar and scroll bar. 
Each frame window can have its own set of menus. There is no 
system wide menu bar. 

Since menusare actually windows, they know how to handle 
all sorts of messages, including user interaction with the mouse 
and keyboard. The menu window typically handles a mouse 
click by tracking the mouse until the user makes a final selection 
from the menu items. At that point, the menu window sends a 
command message to the frame window telling it what menu 
item was chosen. The frame window normally passes the com- 
mand message on to the client window, where your window 
procedure receives the command message and reacts accord- 
ingly. 

Thus, you are not responsible for dealing with menus until 
an item is actually chosen. The menu window, because it is an 
autonomous window object with built in functionality, is able to 
operate independently. You, as the programmer, are responsible 
for defining the contents of the menus and placing them in the 
frame window, but once they are in place they function on their 
own, notifying you only when an interesting event takes place. 

PM menus are normally defined as resources, much like the 
Mac. The standard development tools from Microsoft include a 
resource compiler that processes resource definition files and 
creates resources which are then joined with the code to form the 
executable files. А menu resource definition includes the title of 
the menu, the text of each item, and the command number 
associated with each item. The command number for the item is 
sent as part of the command message when the item is selected. 

One nice feature of PM's resource compiler is that it will 
read the same C header files as the C compiler. Thus, you can 
include the same .h file in your source code and your resource 
definition file to define the constants that correspond to the 
command numbers for the menu items. 


Graphics 

The Macintosh has Quickdraw. PM has the Graphics 
Programming Interface (GPI). GPI is based оп an ІВМ main- 
frame graphics system. It is big and complicated and powerful, 
offering many transformation functions and a store and playback 
mode similar to QuickDraw pictures. 

Where Quickdraw has the GrafPort, GPI has the presenta- 
tion space and device context. The device context is probably 
closest, conceptually, to the GrafPort, in that it is where the 
graphics functions are translated into the operations that actually 
twiddle the bits on the device, be it a screen or a printer. But GPI 
has a higher level gateway, called the presentation space, that 
routes graphics commands to the device context. The presenta- 
tion space takes care of some of the advanced transformation 
operations and the stored graphic playback operations. 

GPl is harder to use than Quickdraw, butit is more powerful. 
Mac programmers will have to start from scratch with GPI since 
there is little overlap between the two systems. 


Multitasking 
The current Macintosh model of multitasking implemented 
in MultiFinder is based on a non-preemptive model. The funda- 
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mental unit of multitasking in the Mac is an application. Basi- 
cally, a application is allowed to run in the background whenever 
the active application is waiting for an event. This is a good way 
to provide multitasking and still be compatible with old software, 
and many programs are already taking advantage of this feature. 

In PM, the basic unit of multitasking is a thread. А process 
(application) can be made up of one or more threads. АП threads 
in the system share the processor by time-slicing, so they appear 
to execute concurrently. A thread is a very efficient unit of 
processing, since it shares global data and most of the machine 
state with its parent process. The thread has only its own stack 
and register set, so the time required to context switch between 
threads of the same process is very short. 

The idea in PM is that you spin off a new thread whenever 
you need to do something that will take you away from the main 
user interface thread for more than 1/10th of a second. For 
example, if the user selects a menu item for a lengthy calculation 
or sorting operation, the application should create a new thread 
to do the operation. The user interface thread will continue to 
execute concurrently with the calculation thread so the user is not 
cut off from selecting other menu items or switching to another 
application while the computation progresses. 

In essence this means that you should never have to put up 
a watch cursor. 

OS/2 provides semaphores and other classic operating sys- 
tem mechanisms to help synchronize and protect shared re- 
sources in a multitasking environment. For example, in the 
previous example of a lengthy calculation, you would want to 
protect the data with a semaphore so that the user could not 
change the data as it was being used in a calculation. 

I think that threads may be the neatest thing about OS/2. I 
wrote а small sample program on both the Macintosh and OS/2. 
The program continuously calculated the roots of a chaotic 
quadratic equation and displayed the results as a graph. On the 
Mac, I used null events to run in the background under MultiFin- 
der. In PM, I created a calculation thread that sent a message to 
the graphing window each time it calculated a new point on the 
curve. The graphing window then plotted the point and waited 
for the next message. The PM version of the program ran quite 
abit faster than the Mac version (Mac II versus Compaq 386/20). 
I don't want to make this out to be some sort of benchmark, but 
I think that the ability to do real multitasking with threads will 
open up many new possibilities for programs. 

Of course, multitasking also creates many new problems for 
programmers who are not used to protecting data and synchro- 
nizing multiple threads, but OS/2 provides the tools needed to 
solve these problems. 


Interprocess Communication 

PM provides a clipboard mechanism that is a superset of the 
Macintosh clipboard model. One nice feature of the PM clip- 
board is that an application can send several formats to the 
clipboard without actually rendering the data. The application 
only has to render the data in a particular format if another 
application makes a request for that format. 

Beyond the clipboard, PM provides several other inter- 
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process communication (IPC) mechanisms, including shared 
memory, pipes, and queues. Іп addition to these traditional 
methods, PM applications can communicate by sending mes- 
sages back and forth between their respective windows. All in 
all, PM provides a richer set of IPC tools than the Macintosh, and 
because these capabilities are present from the start, it seems 
probable that many application developers will take advantage of 
them. 
Development Tools 

Microsoft strongly suggests that you write your PM pro- 
grams in C. The standard development environment is their C 
5.10 compiler and linker, combined with the editor of your 
choice. Microsoft also provides an editor, which is program- 
mable and extensible and totally configurable and takes about 
two weeks to learn how to use. Once you get over the learning 
curve, the tools aren't so bad, but friendly they aren't. It made me 
appreciate how good Mac developers have it with Lightspeed 
and MPW. 

The best part of the development environment, however, is 
CodeView, Microsoft's source level debugger. CodeView will 
let you step through your code in source mode, mixed mode, or 
assembly language mode. It lets you look at variables and set 
break points and break conditions. It is truly a great tool. I spent 
many hours just watching messages flow into my window 
procedures while learning PM. 

The other great part of the Microsoft development package 
is QuickHelp, which is an on-line reference to the system that can 
be integrated with the editor. It works like this: you type a 
function name or structure name or message name in your code 
and want to know more about it. Position the cursor somewhere 
in the name and press Alt-Q; you immediately get full informa- 
tion on the topic. Great tool! 

Iimagine that third party developers will eventually provide 
alternative developmentenvironments. The pre-release versions 
of Microsoft's software development kit (SDK) cost $3000, 
although that price included incremental upgrades over a year- 
long period. Clearly, not too many people are willing to pay that 
much, but I am sure that final retail product will be cheaper by an 
order of magnitude. 

The Good 

I like the messaging architecture of PM. It is actually fun to 
program using window procedures and messages. This is the 
most painless object-oriented programming system I have en- 
countered. It was easier for me to learn than MacApp. There are 
many similarities between MacApp, especially version 2.0, and 
PM. МасАрр 2.0’s use of nested views is very similar to PM's 
nested windows. MacApp, however, is a true object oriented 
environment while PM is only partly object oriented. I think that 
the design of PM benefitted from Microsoft's experience with 
the Mac and two versions of Microsoft Windows. 

Individual menu bars within windows are great. [See the 
November issue of MacTutor. -ed] 

Even though the Z86 has a stupid 64K limit on segment size, 
the built-in memory management and protection between appli- 
cations is nice. 

The graphics are very powerful; in some ways reminding me 
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of PostScript. (see also the graphics entry in The Bad). 

The multitasking model is more advanced than the Macin- 
tosh, but that is understandable since Microsoft had the opportu- 
nity to design it in from the bottom up while the Mac folks had 
to graft it on top of an existing single-tasking OS. 

CodeView and Quickhelp are incredible aids to learning 
PM. They beat anything I have ever seen on the Mac, although 
Ihaven'tseen Lightspeed C's new debugger yet. If Ihad had the 
equivalent of CodeView when I started on the Mac I could have 
learned the Mac in half the time. 


The Bad 

The message-based, object oriented nature of PM has a 
downside. Much of the functionality of the system is hidden from 
the programmer. You inherit an enormous amount of default 
behavior. This is great until you decide that you want to change 
the default behavior. Then you need to know whatto change. PM 
provides a clean way to change the system behavior by sub- 
classing the predefined window classes, but the problem is that 
itis not always clear just which messages to intercept in order to 
change a behavior. With other object-oriented systems, such as 
MacApp, you get the source code for the system objects so you 
know exactly how they work and can use that code as the basis 
for your own subclasses of those objects. Microsoft does not 
provide source code for its standard window classes, so you must 
rely on the documentation to know how they work. This isa real 
problem if you want to do something that the documentation 
team didn't think of. 

The graphics functional interface is too complicated. It is 
hard to do simple things. It is not much harder to do really hard 
things. Some people will love this graphics library, others will 
hate it. Itlacks the elegance of Quickdraw, plus there is no Palette 
Manager to arbitrate colors among windows sharing the screen. 

The file system is compatible with DOS, so you are limited 
to xxxxxxxx.xxx file names. Ugh! 


The Ugly 

The Macintosh screen is beautiful. Ithink all Mac program- 
mers have a deep visual response to the screen. The Mac has lots 
of little touches that make it easy to work at all day: drop shadows, 
proportional fonts, square pixels. The PM screen is pretty ugly. 
I think the difference is the lack of graphic artists on the design 
team. I think the visual look of the screen was designed by 
programmers who were thinking about how difficult it would be 
(and looking over their shoulders at the schedule IB Mis dictating 
for them) to implement the small touches that aren’t there such 
as drop shadows. Of course square pixels are out because of the 
pc hardware, so you can’t really blame the programmer’ $ for that 
one. 

I get the impression that there is no Steve Jobs at Microsoft, 
telling folks that just because something is hard to do is no reason 
nottodoit. Many of the little compromises made in the interface 
inthe name of simplifying the coding have hurt the PM look-and- 
feel. PM just doesn’t feel as good as the Mac. 

Another ugly point is that PM takes at least 2.5 megs of 
RAM; 3-4 megs is more realistic if you want to run several 
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programs at once. Also, although РМ will run on a 286 based 
machine, you really need a 386 to make it responsive. 


Conclusions 

PM is fun to program. The messaging architecture is well- 
designed and allows you to put together very powerful programs 
pretty quickly. One of the main people behind PM is Neil 
Konzen; a legendary hacker and the author of the original 
Microsoft Multiplan for the Mac; so alot of good experience and 
thought has gone into it. 

PM is big and complicated. Expect a learning curve at least 
as steep as the Mac, although your Macintosh experience puts 
you way ahead, conceptually, of the old line DOS programmer 
tryingto makea transition. The windowing environmentis every 
bit as rich as the Mac with the added complication of multi- 
tasking. Be prepared to have your head hurt sometimes. 

As to how you can program in both environments, there 
seems to be some emerging products based on a common library 
idea. Basically, you write your program, or at least part of it, by 


calling functions from a library that can be expressed either in 
Mac ROM calls or PM functions. The library is a higher level 
expression of the common features of both operating systems. 
Such products exist for cross development between the Mac and 
Microsoft Windows, so I have no doubt that they will be devel- 
oped for PM as well. But these libraries cannot hope to cover 
some of the more fundamental architectural differences between 
the two systems, such as the multitasking models. I believe that 
portions of your programs will have to be hand crafted for each 
operating system. 

The bottom line is this,PM is a rich, full-featured, operating 
system that will allow programmers to write applications that are 
as powerful and easy to use as anything on the Macintosh. Do not 
count itout. I think it will be a year or more before it really catches 
on because of the expensive hardware requirements and the lack 
of significant applications, but eventually it will be a big factor 
in the microcomputer industry. 
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Letters & Editorials 


Volume 4 Number 1 


Tool Design the MultiFinder Way 
An Editorial 

Last month we began a series of editorials hi-lighting prod- 
ucts in each category that conform to the new way of doing things 
on the Mac, required by MultiFinder, AppleShare, new menu 
types, and the Macintosh II. We offered Write Now as an ideal 
word processor that meets our expectations for Mac software 
under the “new rules of the game'. Except for the fact that Write 
Now blasts it’s ruler on the desktop, instead of ina window, Write 
Nowconforms very well to the MultiFinder friendly design rules 
that software should follow. Before we look at the database 
category of software, let’s review why Write Now is a good 
example of the new way of doing things: 

* multiple windows work correctly 

Write Now can open multiple documents in re-sizeable and 
moveable windows, one of the chief requirements for MultiFin- 
der friendliness. Windows are very important in the new way of 
doing things, because the user must be able to make the window 
small and shove it out of the way or to another screen while his 
attention is temporarily diverted to another application. Fixed 
size or immovable windows аге a no-no! 

* Single-minded tool 

Write Now does one thing only, and does it well. It does 
word processing! It is simple, straight-forward in use, has no 
hidden feature functions that are not immediately obvious and 
does it's job very reliably. It has two nice features, a built-in 
spelling checker that is very convenient to invoke, and an easy to 
use leading feature which is particularly important for Page- 
maker, which can also import it's files directly and respects the 
leading setting of Write Now paragraph by paragraph. There is по 
“purpose clutter' from a program that can't make up it's mind 
whether it's a word processor or a layout program. 

е Small size and cost 

Since tools must now share the resources, it no longer is 
considered ‘fair’ to be a big system hog and take all the memory 
(and the money!) with large, high-priced software. Write Now is 
inexpensive (under $100), fast and small (80K versus 357K for 
MS Word), so it can co-exist with other tools without requiring 
5 megs of memory. 

* Easy to Learn 

There is a growing trend toward tools that come with six 
inches of documentation and 300K help files! The Mac look and 
feel, if properly implemented, should result in an obvious and 
easy program to learn and use. The Write Now manual is 
reasonable in length and the program uncomplicated, but flexible 
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and powerful for the task it was intended. This is good tool 
design, the Macintosh way. 
FileMaker Plus 
The Best 'Flat' Database 

In the application world of databases, Filemaker Plus has 
always been regarded as the best flat database product on the 
market for any computer. It too follows the new way of doing 
things. The very first version works on a Macintosh II; not many 
programs can make that claim. They have never had to revise the 
program to meet Apple's changing system! I don't know of any 
other significant Mac program that can say that. It is interesting 
that when Microsoft bought PowerPoint from Forethought, they 
didn't buy FileMaker Plus! Is it because FileMaker Plus is far 
superior to Microsoft File? FileMaker Plus is inexpensive, fast 
and small in size (260K), uses windows properly and does a 
single minded job very well and with great flexibility. Nearly 
anything can be imported or exported from the program. File- 
Maker Plus typifies the new way of doing things for a flat 
database product. What we have said for years is that the world 
needs a relational FileMaker. We think we have found it. Read 
on. 

Reflex Plus 
The Ideal Relational Database 


Goldylocks sat on the Hypercard chair and said “This chair 
is too soft”. Then she sat on the Fourth Dimension chair and said 
"This chair is too hard" . Finally, she sat downon the Reflex Plus 
chair and said "This chair is just right" , and she finished her 
database design and fell fast asleep. 


Borland's new relational database, Reflex Plus, is the best. 
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Macintosh database that conforms to the new way of doing things 
onthe Mac. Itis simple to use and operate, very flexible in design, 
low cost (only $275 compared to $500 for dBase Mac), and small 
іп size (250K versus 730K for Fourth Dimension). It completely 
solves the generalized relational problem between arbitrary files 
in a flexible way that makes the generation of complex database 
applications a snap. We converted an Omni 3 database that took 
two weeks to design into Reflex Plus in two days, and that 
includes time to unpack and glance at the manual! On the third 
day, we had added more reports, fields, and files to the design that 
we never did get around to figuring how to implement in Omni 
3. All the information in our Omni 3 database was easily exported 
and imported into our Reflex Plus design. Ап outline of the 
design for a Church membership system or a genealogy system, 
where families and members of families must be tracked, is 
shownin figure 1. This type of application is particularly good for 
checking out database products because it is so obviously rela- 
tional. 
Mac Friendly 

Oneof the best features of Reflex Plus is the ability to use the 
Macintosh way of doing things to design the database file, record 
and field relationships. Opening a new database file, results in a 
graphic box in the overview window. Each entry in the box 
represents a field in each record. Relations between the fields of 
different records in different files are established by drawing a 
line from one field to another! What could be more Мас ish or 
easier than this? The over-all visual effect of being able to always 
see the total database design is both stunning and effective. You 
immediately see new things to add or change in the design, so that 
very quickly you can create the most sophisticated relationships. 
Fourth Dimension also has this ability, but Reflex Plus is much 
easier to set up. In fact, Reflex Plus makes a great template 
designer for Fourth Dimension, but after quickly creating some- 
thing in Reflex Plus, you may not want to bother porting the 
design to Fourth Dimension, unless you want to protect your 
design and sell it. 

Export Function for Reports Needs Help 

Reflex Plus has both an import and export facility, but the 
export function is slightly brain-damaged. It can't export a report 
to a text file arbitrarily. If the report is relational, that is it uses 
nested repeating collections, only one repeating collection at a 
time can be exported, in effect, flattening out the database. We 
think any database program worth it's salt should be able to take 
anything it can create on paper and send it to a text file so that 
reports can be merged into other corporate communications 
electronically, with page layout programs. This is one of the 
strong features of Omni 3 and we would like to see it added to 
Reflex Plus. Other than this small problem, Reflex Plus wins our 
award as the best Macintosh relational database, exemplifying 
the new way of doing things in a Multifinder universe. There 
doesn't seem to be any kind of database application we can't 
create with it in just a few hours. I can't even figure out how to 
get Fourth Dimension booted up in much less time than that! 

Printing in Columns Supported 

One tricky task we wanted to do was to print a report in 

columns. Loree Flescher of Borland showed us how to easily add 
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afew fields to our report to compute the number of lines used by 
the nested repeating collections, and to divide the records into left 
and right side so that the report correctly prints records up and 
down in two columns. Figure 2 shows how this is done, by 
making a ‘calculation report’, and then a second, 'honest-to- 
gosh’ report that copies the fields of the calculation report into 
double columns. 
Make Any Database Print in Columns 

A neat trick to make any database program print in columns 
is to modify the postscript code when the document prints. Press 
cmd-F just after clicking PRINT in the print dialog box and a 
postscript file image of your report will be created. Scan this file 
with a text editor and you should see two lines at every page 
break: 

Ғ Т cp 

%%Раде: ? 2 

By deleting these two lines on the even pages and inserting 
a translate command on the odd pages, after the cp command, 
your report will be automatically formatted into columns, when 
you dump the postscript to the LaserWriter: 


Even pages: replace with 
280 0 translate 


Odd pages: use the following 
F T cp 
-280 0 translate 


$3Page: ? 2 


Тһе cp command is ‘LaserPrep’ shorthand for a macro 
which is defined in the LaserPrep file. Within that macro is a 
show page function, which ejects the page. The translate com- 
mand moves the origin to the middle of the page, so by removing 
the show page, the next page gets printed on the same page, right 
side. On the odd pages, you move the origin back, so the next page 
comes out on the left side. Simple! You might also want to adjust 
the %%Page command with the corrected count of pages as well 
as the last %%Раре command in the file which has the total page 
count, now half what it was. It is amazing what a little postscript 
knowledge can do for you. (We would really like to see a 
definition article that explains most of the postscript macros 
contained in the LaserPrep file. This file can be dumped out by 
pressing cmd-K instead of cmd-F at print time. This would 
greatly help in decoding cmd-F postscript dumps.) 

Get a Big Screen, or Multiple Screens! 

One point of advice, and this probably applies to any 
database product, you should have a large monitor or multiple 
monitors if possible. Working with two monitors on a Mac II was 
areal joy insetting up Reflex Plus applications because there was 
room for the many windows created for the files, entry forms, and 
report forms, all of which are very flexibly implemented. In 
preparing this editorial, I moved the program to a Mac SE and the 
small screen felt very uncomfortable. 

Things We Would Like To See 

A few improvements we would like to see, besides the repair 

of the export function for reports already mentioned, is some 


© The Definitive MacTutor, Vol. 4 


=== Шага. List == 


s)*4 Field selected 
d being defined 


Repeating 
collection of 
families 
Nw i |] Repeating 
Ec | pee Š il collection of 
g —...1........1... ER] famiy members 


HHHHIBIRHATRHHHHHHHHHHHHHHHHHITHHHUBUHHBAOBBOBI 929209 
STITT HHI HHH HHH THT HHH Tt DS 
*25492*020*052*27522*025*520* 095922 09 900 0000 0202020262020 2*022*020*0*8 92920 
4244929292049996%009:6090606000006-900002606000000000009009%0999090044402 22929 
ЕНЕНИНИНИИИНИИНИНИИНИИНВВНИНИНИИИВИЯННЗЛЕ ІЗІ 2940. 
4292429 PHI ИИИИНИНИНИНИННИНИНИИЗИЗІ СІН 
9222227» е 222252929252929292920944949%9202929090409044009000 НН 
RRHH ӨЗІЗЕЗНЕННЕЕННЕННЕНЕИНЕІЕІНІНІЗ НЫ 


IF(PREVIOUS = 0,1,IF((PREVIOUS( 
LineSum)*NumberOf Members) > 
LinesPerColumn,PREVIOUS* 1, 
PREVIOUS)) 


Lines Per Column i 62 у | 
н ОИ кананын жы ы рен КТ Y à 


——— 9 


s] Шага List === E= 
г |LineSum IF((PREVIOUS* 


NumberOf Members) > 
LinesPerColumn, 

NumberOf Members, PREVIOUS* 
NumberOfMembers) 


62 


Lines Per Column 


2 Q 
WW т аот мы O е А а. ао ааа гет... с 
(ec? — к ө — — —  — № ocosuocooqpooooseosQ е o o (E o о cç oo e a o 0 0 e g 0 0 0 oe o o aa. n 2429742 


900006000 
$ee 
Н 
Hind 
292920 
HTuu 
929552 
НЯ 
HETITI 
29292» 
ші НЕҢ 
Ох ИЗ 
829% | |.  * |54522 


ORRA NANANNAARRRARRARNARAANARRRARRRNRRARRARRNRRBRRRA 
2259429292904209929040059099992900527020222949995922929020209929294929)999292954220924225950295956 
ШШ БЫН ИИИ ИИИ ШШ ШИ ШИШ ШШ ИИ ШШШ 
НННИННННИИНН НЕ ЕНИННИНИНИН НЕН НІН ЕНЕНННИННИНИН ИНЕНІҢ 
HIHHIHHIHUHHHHHHUHHUBHHHHEHHHHEHHHHHHEHHHHHHIHBIGHHIHHIHE 
35555555355385335358588838335388538353383888383883883888 


Report Design КЭТ Б 


The second column is defined for MOD(ColumnNumber,2) = 0 
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Step 1: Define a report to print out 
all the family records, with the family 
member records for that family nested 
within the family. This is a nested 're- 
peating collection' on the records of the 
family file and the linked records of the 
member file. 

To get the report to print in col- 
umns, we define extra fields. The first is 
aconstant showing how many lines per 
column we want, placed outside the 
family repeating collection. 

The second, shown selected here, 
is a count of the number of member 
records linked to this family. We add 
four to the numbe because our report 
has four printed lines per family for 
family information. 


Step 2: The column number for the 
family record is computed modulo 2 
from the total line count used so far in 
comparison to the lines per column. 


Step 3: The total line count so far is 
computed by adding the lines of the 
current record (family -- members) to 
the previous value and checking to see 
if we still fiton the page. If not, we keep 
the count the same, otherwise, we add 
these lines. 


Step4: The 'real' report is made by 
duping the ‘calculating report' and 
copying the fields on the left and right 
side of the page. Those families which 
have а 1 in their colmun number in the 


iw] previous report will appear on the left; 
— | | those families which have а 0 in their 
i| column number will appear on the 


right. The five 'calculating' fields on the 
dummy report are not printed. 


689 


additional built-in functions, particulary one to convert a string 
into a number. This seems oddly missing, since the converse 
function of making a number into a string is included. The other 
area of concern, and again this might apply to other products as 
well, is that the Apple date routines are used. As a result, dates are 
limited to something like 1904 to 2039. Well, my Grandmother 
is still living and she was born in 1899 so I can't enter her 
birthdate into a birthday file! Also, I plan to be around after 2039 
so what happens then? A few more formatting options for dates 
would be nice also. We used a LOOKUP function to read the 
string label, “ТАМ” for a month and use it in our reports, so it is 
possible, but it could also be built-in to the product as well. 
Differing Philosophy 

There are two approaches to building a general database 
program. You can make it programmable so developers can 
create commercial templates and sell them to vertical market 
applications. Or you can make it user friendly so the end user can 
constantly adjust, change or modify the design in a Mac-like 
friendly way. This eliminates the need for database programmers 
in many applications. Borland has taken the latter approach with 
Reflex Plus, while programs like Fourth Dimension and dBase 
Mac have taken the former approach. (Some might argue that you 
can do both in one program.) We think Borland is right on target 
with their approach. A well-designed database program should 
not have to be programmable to be flexible. There is however, a 
legitimate need for database designs that are programmable and 
unchangeable. For some applications, the ease with which you 
can change a Reflex Plus design may be a problem (a protect 
object menu item is provided, but no password protection). And 
itis not clear how suitable Reflex Plus would be for a multi-user 
application over AppleShare, where more than one Mac user 
must work on acommon database at a time. It appears the product 
is best suited for the single user category. In any case, the program 
best exemplifies good use of the Macintosh user interface, and 
conforms to the expected Mac behavior and ease of use most of 
us love about the Mac. After using it, Iam convinced I can create 
any database application in a matter of hours with this product. 
And with my busy life, the speed with which I can “figure it ош” 
and get the job done is very important. (Too bad MPW can't be 
like this product!) 

Colorizer Restores CMD-Shift-3 
Kenelm W. Philip 
Fairbanks, AK 

Ithink you owe an apology to Joel West (Palomar Software). 
In the November issue of MacTutor, you comment on page 12: 
“There is still no way to capture the screen image of a color 
display." On page 6 of the same issue is an ad for Colorizer, 
which mentions that this program will "Record full-color screen 
images to disk or printer". Apparently the left hand knoweth not 
what the right hand is doing... 

As a satisfied user of Colorizer, I can vouch for the fact that 
the package contains an FKey which will dump a color screen to 
disk as a PICT file. To my mind, this FKey alone is worth the 
price of the package. /We agree! -Ed] 

Finally, a tip that may be worth passing on to those Mac II 
owners who happen to have more than one monitor hooked up: 
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If you hold down the Command key when you drag the grow box 
on a window, you can overcome the built-in limits on window 
size that many programs have (for example: Reflex+), but fails 
for a few (for example: MacWrite 4.6, whose window will snap 
back to the built-in limit as soon as you release the grow box). [If 
Reflex Plus has any limitation on it' s window size, we can't see 
it on an Apple color monitor! -Ed] 
68020 versus 80386 

William Clodius 

Los Alamos, NM 

I have a few comments on the recent discussions that have 
appeared in your magazine on the relative performance of the 
80386480387 compared with 68020-68881. I believe your 
readers are incorrect in implying that a flawed design necessarily 
implies lower performance. The problems with the 80x86 design 
include the use of segmented memory, a smaller number of 
registers, and incompatible memory modes for different sizes of 
memory space (the 80286 protected mode problem). These 
problems complicate the design of programs, particularly of 
large ones, and make it impossible to write a program for earlier 
chips that take advantage of the larger memory space of subse- 
quent chips. The need to implement several memory modes on 
the 80386 also increased the complexity of the design, and hence 
may be a contributing factor to Intel’s well publicized difficulty 
in manufacturing the 80386. 

However, while the above problems complicate a 
programmer's task and increase the cost of a working 
80386480387 system, they do not directly affect the perform- 
ance of the system. For systems of comparable complexity, ie. 
two CISC designs, the performance should be roughly propor- 
tional to the MIPS rating. Because the 80386 includes the MMU 
on chip and uses a higher transistor density to implement faster 
algorithms for some instructions, it takes one to two less clock 
cycles than the MC68020 with MMU to perform an instruction 
So that it is effectively 15-33% faster than the MC68020 at the 
same clock speed. This increased performance is not unreason- 
able given that the 80386 appeared well over a year after the 
MC68020, and its designers could both study the MC68020 for 
ideas and take advantage of improvements in manufacturing 
technology. However, it is significantly less than that suggested 
by the recent notorious Byte articles. 

The above disagrees with analyses by some of your readers 
that assume that the 80386-80387 differs in performance from 
the 80286-80287 only by a factor proportional to their clock 
speed. However, by the same reasoning a 16MHz MC68020 
should be only twice as fast as an 8MHz MC68000, instead of 
about four times as fast. In such comparisons it should be noted 
that a 32-bit bus in and of itself will give an additional factor of 
two improvement for 32-bit operations over a 16-bit bus (ie. 
floating point operations), and can give additional performance 
increases for 8- and 16-bit operations by using the registers as 
caches and by sometimes performing operations in parallel. 
Further performance increases occur for newer designs because 
the increased transistor density allows the implementation of 
faster algorithms and special techniques, such as putting the 
MMU on chip, to reduce the number of clock cycles per instruc- 
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tion. Such techniques allow the MC68030 to be about 50% faster 
than the MC68020. The increased transistor density also allows 
the use of new instructions, such as the transcendentals imple- 
mented on both the 80387 and MC68881. As a result, your 
readers should not predict the performance of an 80386 system 
using an 80286 compiler, although some of them have attempted 
to do so. 

Finally, a few assorted points. Neither the 80387 nor the 
MC68881 is the fastest available floating point unit. The Weitek 
processors, for example, are much faster than either chip at 
floating point operations. Although I believe the 80386480387 
is faster than the MC68020+MC68881, the performance differ- 
ence between the two groups of chips is not significant compared 
with reasonable differences in compilers, operatin gsystems, and 
bus characteristics. However, if Motorola's performance goals 
for the MC68030+68882 are achieved, then their performance 
should be much faster than the Intel chips for reasonable vari- 
ations in other aspects of the system design, ie. a Mac “III” should 
decisively outperform any 80386--80387 system. 

Does Font/DA Move 3.6 have any bugs? 
Peter Trinder 
Berkshire, England 

I have a technical question to ask in respect of MultiFinder. 
Ihavereceived from Apple Developers group (the UK version of 
APDA), the UK localized version of MultiFinder and I have 
encountered some weird problems using the 3.6 Font/DA Mover. 
The main trouble seems to be that when I remove more than one 
Font, the Font/DA Mover fails with an error (-108) and the font 
file becomes damaged (or if I am removing from the system, the 
System is damaged). I only seem to get this problem using a 
MacPlus with more than 1Mb of memory, in my case it is a 
TurboMax. A friend has had this problem on a standard MacPlus 
with 4 Mb! Ichecked with Apple UK and they told me on 16th 
of November that the release of MultiFinder [in the UK?] had 
been delayed. Does anyone know if this is the reason? I called 
Steve Brecher abouta week before I heard of the delay and he was 
puzzled but could not offer a solution. 

[Multifinder is shipping here and we have not seen this 
problem with the FontlDA Mover. However, you cannot ‘edit’ 
your systemfile while running Multifinder. You must return to the 
normal Finder before you move fonts and DA' s in and out of the 
System. The only problem we have verified is that which we 
reported last month: some fonts may need to have their flag word 
checked in their FOND resource to make sure it is $6000 to work 
correctly under Pagemaker 2.0a. We also noticed that Edit has 
problems with more than 24 fonts under the new system. -Ed] 

MultiFinder Patch for PageMaker 

He did however give me a patch for PageMaker 2.0 & 2.0a 
which will allow it to switch correctly in MultiFinder; the 
problem is that PM only recognizes 31 entries іп the Apple Menu. 
Switching in MultiFinder looks for the entry in the Apple Menu; 
if itis more than 31, nothing happens. To fix this, search for 0102 


011F and change it to 0102 O1FF. This will allow PageMaker to | 


honor 255 entries. Thanks Steve, you are great!! 
Riccardo Ettore came to the MacUser show in London (10- 
12 Nov.) and gave me a disk with his new Sound Mover 
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Package. This has a converter for taking SoundCap files and 
producing .snd resources for both HyperCard and the Mac II. He 
has also included a Sound Mover which is designed like the Font/ 
DA Mover and this will install sound resources into the system. 
Of interest to MacPlus and SE owners is his IBeep2 CDEV which 
is placed in the system folder and appears in the Control Panel 
(System 4.1 or higher) and allows the Mac II beep sound facility 
on these machines. He has included an assortment of sounds, I 
have the Beatles HELP! Makes a nice change. It should be on 
CompuServe by now. [Note to authors: We would dearly like to 
publish some type of sound mover CDEV that explains how to add 
sounds to the Mac II ‘library’ of exception beeps. -Ed] 
Draw over the Menu Bar in Basic 
Anthony J. Oresteen 
Batavia, IL 

One of my biggest frustrations with ZBasic for the Mac was 
Icouldn't control the ENTIRE screen. I wanted to draw over the 
menubar but justcouldn’t. Well, thanks toa hint from Ann Arbor 
SoftWorks (FullPaint) I figured it out. 

The solution is simple (as most are once you know them!). 
You can draw visable windows only on the defined region of the 
desktop. When the Window Manager is initialized, it draws the 
desktop and empty menu bar. It stores the desktop as aregion and 
the global variable GrayRgn (&9EE) holds a pointer to it. By 
expanding the desktop region to the full screen size, youcan draw 
windows over the full screen. 

Below is a program that draws a full screen, inverts it to 
BLACK, and then restores the desktop. NOTE that it will work 
with any size screen as it checks the global screen.bits for the 
screen size. 

Two bugs remain. First, the lower corners of the desktop do 
not return to “round rect” types. They are square but should be 
rounded. Secondly, when scrolling textin the black window, you 
get funny white bars. Any help on solving these minor bugs 
would be appreciated. Thanks. 

REM THIS DRAWS WINDOW OVER MENU BAR 
REM A. J. ORESTEEN AUG 1987 
REM PUBLIC DOMAIN USE FREELY 


REM THANKS TO ANN ARBOR SOFTWORKS C"FULLPAINT^) FOR HINT! ! 

REM USE ZBASIC 4.0 [ог later? -Ed] !!! 

BREAK ON : CLS COORDINATE WINDOW WINDOW OFF 

VSIZE8= PEEK WORDCPEEK LONG(&904)-116): REM VERT SIZE OF 

SCREEN 

Н517ЕЖ- PEEK WORDCPEEK LONG (&904)-114): REM HOR SIZE OF 

SCREEN 

GRAY&=PEEK LONG (&9EE): REM GETS GRAY REGION OF DESKTOP 

CALL OPENRGN : REM SAVES REGION DATA 

OLDDESKTOP&=FN NEWRGN : REM GETS NEW HANDLE FOR REGION 

CALL COPYRGN (GRAY&,OLDDESKTOP&) : REM GETS A COPY OF 

STANDARD 

DESKTOP 

CALL SETRECTRGN CGRAY&,0,0,HSIZES,VSIZES): REM SETS DESKTOP TO 
FULL SCREEN 

WINDOW 81,,(0,0)-(Н517Е%,У517Е%2,3 : REM DRAWS MAX SIZE 

WINDOW 

PRINT “BIG WINDOW!” 


DELAY 1000 


WPTR&-WINDOW (14) : REM HANDLE TO WINDOW 
VISRGN&-PEEK LONG CWPTR&*24) : REM VIS RGN OF WINDOW 
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CALL INVERTRGNCVISRGN&) : REM INVERTS SCREEN TO BLACK 


CALL BACKCOLOR (33) : REM BLACK BACKGROUND COLOR 
CALL FORECOLOR C30) : REM WHITE FOREGROUND COLOR 
CLS: BEEP : TEXT 0,18,0,0 

PRINT : PRINT “BIG BLACK WINDOW!" 


DELAY 1000 


WINDON CLOSE #1 : REM CLOSE FULL SCREEN WINDOW 

CALL BACKCOLOR C30) : REM WHITE BACKGROUND COLOR 

CALL FORECOLOR (33) : REM BLACK FOREGROUND COLOR 

CALL COPYRGNCOLDDESKTOP&,GRAY&): REM RESTORES NORMAL DESKTOP 
REGION 

CALL PAINTRGN (GRAY&) : REMDRAWS REGION 

CALL DISPOSERGN COLDDESKTOP&) : REM DON’T LEAVE A MESS IN 
MEMORY 

CALL DRAWMENUBAR : REM RESTORES MENU BAR 


WINDOW #2, “FULL SCREEN”, (20, 40)-CHSIZES-20, VSIZE8-20), 257 
TEXT 4, 12,0,0 

PRINT:PRINT *MENUBAR IS NOW SHOWN AGAIN!!^ 

BEEP 

PLOT 40,80, TO 200,200 : CIRCLE 300,200, 40 


“PAUSE” 
GOTO “PAUSE” 
Hypercard Questions 
Scott Vore 
Indianapolis, IN 


A few questions please: 

1) In Hypercard is there any way to call the SF GetFile 
dialog when importing text or do I have to specify the 
Filename each time? (I guess I could use CN XCMD) 

2) InHypercard is there any way to use application defined 
events like event #13-15 in the Event Manager? 

3) The October issue of MacTutor (pg. 7) spoke of a button 
to import text in the button ideas stack. I sure can’t find 
it. Any ideas? 

4) Any idea why a company that calls itself (or product) 
“Lightspeed” won’t whip an update for Lightspeed 
Pascal for the Mac II without a check (not plastic) and 
then takes over two weeks to do it? Beats me. 

[The latest LS Pascal update, 1.11, is available on Ap- 
pleLink (I think), Compu-Serve, and direct from MacTutor at no 
charge to our customers. A new version should be announced at 
the Expo this month. More next time, if they release it. We have 
had a number of people contact us about writing regular Hyper- 
card articles, but nothing yet. We would like to have an on-going 
hypercard column, if someone has the ‘stick-to-it’ fortitude ofa 
Dave Kelly or Jórg Langowski to pull it off. -Ed] 
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Making WriteNow MultiFinder Friendly 
Mr. Sleazy Hacker 
Boulder, Colorado 
Here's a very sleazy patch to get around WriteNow's habit 
of blasting a ruler across the entire screen (assuming a Mac II 
sized screen of width 640 pixels). The patch was applied on a 
Mac II with B/W monitor, and version 1.0 of WriteNow. 
Using Fedit or equivalent, search for: 
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А918 2F@C 2055 3F28 FF92 5557 ЗЕЗС 002C 

And replace with: 

A91B 2FOC ЗЕЗС 0258 4Е71 4ET] 3F3C 0020 

There's one occurrence of the pattern. What we are doing 
here is replacing: 


помеа.1 (a5),a8 
move.w ff92Ca5),-Ca7) 


Subq.w #2, (a7) 


_SizeWindow 
with: 
move .w 1$250,-CaT7) 
nop 
nop 


“SizeWindow 
In other words, the code fragment that calculates the width 


of the ruler as (screenBits.bounds.right -2) is replaced with one 
that supplies a constant value of $258 (decimal 600). [Note to 
developers: they never should have used screenBits.bounds for 
this calcuation. Since their ruler is in iť s own window, as David 
Dunham points out below, it should have been defined as a fixed 
size window or better still, growable. -Ed] The largest argument 
that subq will take in this form is 8, hence the substitution with 
a constant. Of course, once you've done this screen-size inde- 
pendence flies out the window, so don'tdo itto an original...(You 
can find this peice of code with TMON by putting a trap intercept 
on GetNewDialog, launching WriteNow and waiting for the first 
intercept. GetNewDialog is immediatly followed by a MoveW- 
indow and the SizeWindow shown above.) 

When the ruler is shortened by 40 Pixels in this fashion, 
there's just enough room for part of the top Finder icon to peek 
through. 

Since this trick is so sleazy, I think I'll request anonymity of 
you decide to publish it! [Granted! -Ed] 

By the way, there's one MacWrite feature that I especially 
miss under MultiFinder when using the newer word processors 
- its ability to put formatted text on the clipbord (the *MWRT' 
scrap format). Microsoft Word, WriteNow (at least the version 
I tested) don't do this, so you're cutting and pasting plain text. 
Since PageMaker seems to understand this scrap format, that's a 
pity. The "MWRT"' format isn't perfect — you can't pass leading 
values, specify baseline offsets or odd-ball styles like strike- 
through, but it's better than nothing. I’m hoping that there will be 
some improvement in this area in 1988. [We agree! The whole 
point of developing a new Text Edit was to support a new 
formatted text type for the clipboard, but no one is using it yet! We 
encourage developers to standardize on support for the new 
formatted text type in cutting and pasting across applications. 
How about an article to encourage this someone? -Ed] 

Reflex Plus Comments 
Kenelm W. Phillp 
Fairbanks, AK 

It was with great interest that Iread your editorial on Reflex 
Plus in the January '88 issue of MacTutor. After reading it, 
however, I wrote the enclosed letter in the attempt to urge 
Borland to fix two defects (one annoying, one serious) in the 
existing versions of reflex Plus. 
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P.S. If you will reread my previos letter ( which you printed 
in the January issue), you will see that I was talking only about 
Mac II systems with two monitors when I mentioned the 
"COMMAND-Grow. Box" method of expanding windows. 
Both Reflex Plus and MS Word, for example, will notallow you 
toexpanda single window to cover two mmonitors without usin g 
this handy trick. 

Iam glad to see your editorial on Reflex Plus in the J anuary 
issue of MacTutor. I have been using Reflex intensively since it 
first came out from Singular Software as Interlace in 1085, and 
I Have found the program to be almost ideal for my purposes ( 
which involve maintaining data on a research collection of 
Alaskan insects). However, I think your readers should be aware 
of a couple of disturbing problems that have emerged, one 
involving the use of Reflex with Apple System versions 4.1 and 
later, and the other involving Reflex Plus. 

Date Formatting Limited 

Problem # 1 has to do with the formatting of fields declared 
tobe of type ‘date’. According to the manual (for both Reflex and 
Reflex Plus) there are three date formats: 

° — short: 12/31/84; 

°  long:December 31, 1984: 

°  abreviated: Dec 31, 1984. 

Unfortunatly, this is not the case with System 4.1 or 4.2, 
where both the Long and Abbreviated formats add the weekday 
name, becoming: 

e Monday, December 31, 1984 

° Monday, Dec 31, 1984 

I have verified this problem for Reflex 1.00 and 1.01, and 
Reflex Plus 1.00 and 1.01, with Systems 4.1 and 4.2. 

For my work on insects, dates are very important but 
weekdays are not. It was disconcerting to find that all my carfully 
formatted reports were fouled up by the addition of an extraneous 
and unwanted weekday name in date fields as soon аз I upgraded 
to System 4.1. Itoccurred to methatthe problem might very well 
lie in the International Resources in System 4.1, and that it might 
be possible to hide the weekday by activating the 'supress 
даупате” byte in those resourses. I ran into some problems 
trying to do this, so Isentarequeston AppleLinkfor help with this 
operation. To my vast astonishment (remember that Apple and 
Borland are currently engaged in a joint promotion campain for 
Reflex Plus!) the reply was, in essence: “We do not recomend 
using ResEdit on applications. We suggest you try another 
database.” I had not even suggested using ResEdit on Reflex 
Plus. 

I then wrote Borland. They replied that the problem lay 
entirely with Apple’s System software. Somehow, I was expect- 
ing them to say that— But the problem remained. It also looked 
as if the technical support people at both companies were totally 
unaware of the Apple/Borland joint promotion campaign. 

I was able to elicit a workaround for the problem. If you 
declare the field to be of type ‘text’ in your report, you can 
constuct a formula which will put the date into any form you like 
(without weekday names)— and Borland was kind enough to 
supply me with such a formula. I reproduce it below for the 
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benefit of other people who have run into this other wise intrac- 
table problem. Assume that your date field is named "WHEN', 
and you would like dates in the format: 31 Dec, 1984. Use the 
following formula in the report, where the new date field is a text 
field: 

DAYCWHEN)” “& IF CMONTHCWHEN )=1, “Jan” IF CHONTHCWHEN 2-2, “Feb”, 

IF CMONTHCWHEN 2-3, “Mar” IF CMONTHCWHEN 2-4 “Apr”, 

IF CMONTHC WHEN 2-5, “Мау”, IF (MONTHCWHEN )=6, “Jun”, 

IF CMONTHCWHEN )=7,, “Jul”, ІЕСМОМТНСИНЕМ2-8, “Aug” 

ТЕ CMONTHCWHEN 2-9, “Sep”, IFCMONTHCWHEN )= 10, “Oct”, 

IF CMONTHCWHEN >= 11, “Nov”, "Dec^222222222)2&^, “&YEARCWHEN) 

A slightly different version of this formula is available from 
Borland as Tech Info note #370, “Truncating the day of the 
week”, date 28 september 1987. [We used a better refinement of 
this method by setting up a look-up table file to associate the 
month name with the month integer. This is a more elegant 
approach than the massive If... Then.. Else statement. -Ed] 

We are not out of the woods yet. A date field ina report so 
formatted will not sort by date. If you need to sort your data in 
chronological order, and you have Reflex(rather than Reflex 
Plus) youare out of luck. In Reflex Plus youcan do the following: 
create one report in which the date field is of type ‘date’, and sort 
that report on date. Create another report in which the date field 
is declared to be of type ‘Text’, using the formula above—and 
then call the repeat rectangle from the first report in the second 
report (see page 184 in the Reflex Plus manual: “accessing Data 
in other reports”). This cumbersome workaround will take care 
of the problem—but it’s a kludge! Apple and Borland should get 
together and solve this problem. [Borland is right in saying that 
Apple modified the International date routines, which many 
companies use as is to avoid having to duplicate functions 
already done by Apple. But Borland should add to their built-in 
function list to include more date formatting functions. However, 
this is minor compared to the limitations of the exportation of 
reports I reported last month! My brain-damaged report expor- 
tation ftx should be at the top of their “things to do' list! -Ed] 

Header and Footer Pr oblems 

Problem $2 is one that Borland introduced with Reflex Plus 
(both version 1.00 and 1.01). Something went wrong with the 
formatting of headers and footnotes in reports, and they now take 
up the entire space within the header and footer boxes even if they 
are only one line in length. that in : a one line header will be 
separated from the body of the text by about 1 3/4" of blank space; 
and a one line footer will have about 1 3/4" of blank space 
between itself and the end of the page, leaving about 6" of space 
for the textof the report. I have not yet verified this problem with 
all concievable configurations of hardware, but it has turned up 
with the following: Macintosh+, System 4.1, 15" ImageWriter; 
Macintosh II (2 MB ВАМ), System 4.2, 15" Image-Writer; 
Macintosh II (5 MB RAM), System 4.2, Laser Writer-from which 
Iconclude that this is almost certainly a universal problem with 
Reflex Plus. 

I called Borland about this situation, since I found Reflex 
Plus essentially unusable when it came to printing my data in 
properly formatted reports. The first response I received from 
Tech Support was that I had run into a problem that sometimes 
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occurs when you take a Reflex database into Reflex Plus, and that 
| Ishould throw away the existing headers and footers and re- 
install them from within Reflex Plus. That accomplished noth- 
ing-so I created a new test database file from within Reflex Plus, 
and, as I suspected, the exact same problem turned up. I called 
Borland again, and Tech Support now (reluctantly) admitted that 
they had received a number of angry calls about this problem. 
Nothing was said about when or if a fix would be made available. 

I find itimpossible to believe that beta testing did not expose 
this problem (unless Borland does not do beta testing). Iam thus 
forced to the unpalatable conclusion that Borland released Reflex 
Plus unfinished, knowing it was not in fact yet suitable for the 
business environment for which it had been targetted. I had 
written Borland earlier to inquire if the major price increase in 
Reflex Plus would be accompanied by a proportional improve- 
ment in their user support, since their previous policy had been 
not to notify registered owners of upgrades. They assured me that 
I would be seeing a totally new level of support for Reflex Plus. 
It seems to me that one of the first steps in user support might be 
to provide customers with a business database that could print 
proper headers and footers... 

I totally agree with the main thesis of your editorial-Reflex 
Plus is potentially a fantastic program, and would be my pre- 
ferred database environment if it could only print decent reports. 
For the time being, however, I have archived Reflex Plus and 
returned to Reflex, which can handle headers and footers. [If my 
export problem were fixed, then you could export the report to 
Pagemaker and format it anyway you like! -Ed] 

Color Scanning 
Douglas K. Beck 
Los Altos, Ca. 

As to things that seem to work on the Mac II: The PCPC IHD 
144 internal disk installed the first time with just a screwdriver, 
came up with no trouble and has performed with speed and 
efficiency, 10 hours a day and more, for a couple of months now. 

The RasterOps (Cupertino) 24 bit RGB controller is also 
performing up to expectations. I have written some display 
programs for it and it works up to the book with few misunder- 
standingsl I scanned some 1024 x 768 pictures from some 8x10 
color positives that look fine. One picture of the Stanford Chapel, 
full of textures and fine detail, a bouquet of flowers and some 
color test patches, including the Macbeth color test pattern. Гат 
driving a Mitsubishi HG6905BK 20 inch color display with the 
RO board. I am less enchanted with the monitor. All common 
adjustments require dismantling the thing since they are buried 
on the main pc board. A long insulated screwdriver is required, 
and you must fish down past the second anode terminal to get to 
them. Sigh. 

Ihave received the National Instrument DMA controller, but 
have not tested it. Looks interesting, and uses an Intel chip to do 
the transfer thing. 

Still to be received are the National Semi 16 Megabyte board 
and the Optronics 400 meg WORM unit. I will report how they 
work if desirable. 

One thing that is causing pain right now, is having to convert 
from Megamax C to Lightspeed C to gain access to the color stuff 
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on the II. Megamax is not going to support their Mac product any 
longer, and have orphaned the product just as it is coming of age 
оп a machine that has the speed and multitasking capability to 
make it viable. Lightspeed is a nightmare. The inconsistent 
handling of strings is pitiful. With Megamax, all strings were C 
strings and the compiler took care of all the conversion work. 
Lightspeed lets you guess, Pascal or C this time? Bah. Can't 
someone lean on Megamax and get them back in the game? 

Spleen vented. Flame off. [A better approach would be to | 
lean on Think to enhance their very popular C compiler to make 
string handling easier. -Ed] 

I agree on WriteNow. I recommend it without reservation 
for all but the heaviest of duty tasks. 

Incidentally, making mailing labels with HyperCard has 
been apain. The ImageWriter is just not up to the task. However, 
if you get some Avery 5331 liquid toner copier labels (for use 
with the Cano Engine) the LaserWriter does a very creditable 
job. Looks neat on the Christmas Cards. [I use a very solid NEC 
Spinwriter for mailing labels for MacTutor’ s 13,000 cirrcula- 
tion. Apple simply does not make a business printer that can do 
labels reliably in the volume we need. The Spinwriter, however, 
isa truck. It can run all night and never jam. But it was a pain to 
get it working with the Mac! -Ed] 


Speaking of Christmas, a Merry one to you and the very best 
for the New Year. 
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Spreadsheet / Word Features 
Steve Millina 

In theJanuary issue 1988 letter column, Cary Maraish asked 
how to do spreadsheet-type windows fairly easily . I just did a 
one-page spreadsheet, and I found that the list manager does a 
great job. Set up a rectangle for the cells, and feed Linit the 
number of rows and columns, but FALSE for both scroll bars. 
Since this was a true spreadsheet, actual text entry was through 
atext edit box atthe top of the page, with the text being transferred 
to the list with LSetCell only when the user indicated entry was 
complete. For convenience, I used a dialog window so that the 
text edit stuff was taken care of directly. You do need to bear 
in mind that the default text list definition proc justifies left , so 
the programmer has to insert the appropriate number of spaces in 
front of the numbers to make them line up. 

If you really want entry to be made at the selection, you 
might try a Dialog window with a grid of edit text boxes. (I tried 
something similar with a grid of stat text boxes and it worked 
fine). 

Since I’m already writing, I want to take issue with your 
evaluation of WriteNow. I tried desperately to like WriteNow for 
many of the reasons you mention, but in the end I went back to 
Word 3. The most important determinant was the fact that setting 
line spacing was a slow and painful process, because I use lots of 
single spaced paragraphs (for examples and quotations) in the 
midst of double spaced text and the switch took forever. So does 
setting the ruler. 

leven tried macros. At the time I didn’t have Quickkeys but 
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Idid һауе Touch-n-Go, which is usually great. I tried to make it 
move the indent cursor. Fat chance! WriteNow doesn't look at 
the mousedown and mouseup events once it knows what's going 
on and the indent moves sort of randomly. I guess it reads the 
mouse button directly but that is not the kind of programming you 
should commend 

Word, on the other hand, may be mammoth, and may have 
any amount of code wasted on oddities (such as outlining that 
only an IBM PC could love) but a lot of the add-on touches are 
incredibly useful. Styles lead the list. Also high is the command- 
= calculator that calculates whatever is selected and makes the 
answer directly available for pasting. Iknow уой сап do the same 
thing with some calculator DAs but the difference in speed and 
convenience is simply amazing. In a lot of respects, Microsoft 
did what good programmers are supposed to do, it found out how 
its targeted users work. 

Big Arrays for С 
Jack McCrae 
Albuquerque, NM 

The enclosed program would probably be appropriate for 
the inclusion in the letters section of your most excellent maga- 
zine. At least I think it’s kind of neat (my program thatis). And 
if it wouldn’t be too much trouble would you please send me a 
copy of of your author’s kit. 

Two limitations I have run into while programming in the C 
language are the 32k byte segmentation limit, and C’s inability 
to pass variable sized multi-dimensional arrays to subroutines. I 
have found a simple solution to both of these problems. Arrays 
constructed according to the source code which follows act like 
‘normally’ declared arrays; no special functions are needed to 
assign into, or read from these arrays. 

The following example program illustrates a three dimen- 
sional case. It can be easily modified for two dimensions, or 
extended for four or more. The cost of this method is a small 
amount of extra space which is required for one or more arrays 
of pointers, and an extra initialization Step to create these point- 
ers. As an added bonus, rows of these arrays may be rearranged 
by simply rearranging the pointers to them, rather than all of their 
elements themselves. 

To use this method to create an array that takes up more than 
32k bytes of memory, delete references to the variable 
'arrayspace'and replace with the line 

Шыны Ба 

"internedeteLi1L Jena? loc(sizeof (double )*kdenension); / 


where kdemension is the number of elements in the outer- 
most dimension. 

This swaps the 32k total limit for an array for a 32k limit on 
each dimension. 

The following compiled with either Megamax C, v 2.01b. or 
Lightspeed C v 2.13. 


tinclude«stdio.h» 


extern long tickcount 0); 
long t; 
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usearrayCarray) 
double**erray[]; 


printf(“arrau[0][0][0)=%f /n’, аггау[9 (01101); 
printf (“аггау[ 1112] [3 1=Я1 /n* ,errey E 11(21(32); 
printf (“arrau[2][3][4]=$f /n", аггау[21[31[41); 
printf(“arrau[9][9][9]=%f /n", array[91(9] (91); 
/*note that the above arrays appear to be accesed normally. 
Над а pointer to а ‘normal’ array (і.е. erreyspace[ 1) been passed 
instead of **array(] it would have been necessary to use a 
construction like аггаузрасе [1х 100=]*10=к] to access array 
elements. 


idi 


/*this routine sets up ‘array’ to index elements of 
‘arrayspce’ by double indirection */ 
initerreyCerreyspace, intermediate, array) 
double аггауврасе(10111011101; 
double *intermediatel 191[ 10]; 
i **errey[ 10]; 
int i,j,k; 
forCisz0;j«10; }++)( 
erray[ilsintermediate[i]; 
Гог(]=0; j«10; j**5( 
intermediate[i][j)=arrauspace[i][j]; 
for(ksQ;k«10;k**) 
errayspace[i][j][k 12 100*i* 19* jk ; 


) 


main()( 

int i,j,k; 

double arrauspace[10)[10][10); 

double *intermediate[10)[10]; 

double **аггау[ 10]; 

initarrayCarrayspace, intermediate, array); 

asearray(array); 
whileC!button()); 


) 

Higher Printing Authority 
John Bartleson 
Spokane, WA 

First let me thank you for producing such a useful journal. I 
read it cover-to-cover every month and have found many useful 
items in its pages. MacTutor fills a unique place in the evolution 
of our favorite computer. 

Iam thinking of writing an article for MacTutor, but I need 
your advice on whether you would be interested in the topic. Here 
it is: 

As I began to program the Mac, I had to tackle the problem 
of writing printing code. I eventually learned how to do it, butI 
think that the effort necessary to “do it right" was too high. There 
are several reasons for this. First, like much of the Macintosh 
system software, the Printing Manager is a relatively low-level 
interface to a process much different from that used on previous 
computers. Second, the Printing Manager as documented in 
Inside Macintosh is vague on many topics and needs to be 
rewritten. Finally, there is very little non-Apple documentation 
dealing with how to use the Printing Manager. The only docu- 
mentation I've found is in Volume II of Dan Weston's The 
Complete Book of Assembly Language Programming. This has 
agood chapter on printing but it leaves out some of the fine points 
necessary for commercial - grade programming, such as error 
recovery. 
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Programming for Macintosh is more complex Шап is readily 
apparent from Inside Macintosh. You have to take care of draft 
copy looping, max pages in spool file looping, print-idle proce- 
dures, print traps vs. direct calls, etc. On top of this, you have to 
provide robust error checking that can handle both user cancel- 
lation, which may occur atany time, and Printing Manager errors. 

I found that I was wrestling with these problems every time 
I wrote Printing code for a program. I wanted a higher - level 
interface to the Printing Manager, one that would be easier to use 
than the existing interface, but one that wouldn't limit me in 
getting any desired image on the page. This led led me to write 
the Generic Printing Manager, GenPrint. 

GenPrintis a single subroutine that communicates with your 
calling program through a parameter block named GenPrBlk. 
GenPrBlk contains several flags and handles, and in addition it 
contains pointers to several co-routines. Co-routines are proce- 
dures within your calling program that do your specific print 
processing, GenPrint calls these procedures at appropriate times 
during printing. There are four co-routines, but the typical 
program will use only two. For example, you must provide a 
PrintPage co-routine to image the pages, but a JobDialog co- 
routine is needed only if you have a custom PrJobDialog you 
want to execute. Here's an example of typical use in pascal: 


PROCEDURE MyPrint (Demo of GenPrint call); 
VAR ParaemBlk:GenPrBlk; 

(other variables owned by MyPrint would go here these can be 

accessed within the co-routines. 

PROCEDURE GenPrint (Blk: бепРгВ1к >) ; EXTERNAL; 
PROCEDURE DoInitCopy; 
(Initialize pointers etc. 
END; (DoInitCopy) 
PROCEDURE DoPrintPage; 

( Drew а page in the printing GrefPort ) 
END; (DoPrintPage) 
BEGIN (MyPrint 

( Set the co-routine addresses in ParamBlk ). 
ParamBlk.JobDialog :=0; 
PeramBlk.SpSpece :-0; 
ParemBlk.InitCopy := eDoInitCopy; 
ParamBlk.PrintPage := @DoPrintPage; 


to print a copy) 


кк. (PeremBlk) ; 
END; (MyPrint) 


GenPrint is written in MPW Assembler, which is necessary 
so that it can set up the caller's A6 stack frame to allow the co- 
routines to access their enclosing procedure's variables. This 
means it can be called only from assembler or from languages 
(like MPW Pascal and C) that allow external assembler subrou- 
tines. 

GenPrint greatly reduces the amount of coding necessary to 
do Macintosh printing. As an example, А commercial - class 
subroutine to print any Text Edit record, with support for fixed- 
space tabs, can be done in about 40 pascal statements. 

While this technique may not be as exciting as an article on 
anew 256K ROM feature, I suspect a lot of people who haven't 
figured printing out would find it useful. And nothing on this 
topic has appeared before in MacTutor. 

[Sounds great. Looking forward to seeing this. -Ed] 
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Dialog Boxes 
David Dunham 
Goleta, CA 
Ithink Kirk Austin (Vol. 3, No. 12, p.73) has the right idea; 
“аһош” dialogs should be unobtrusive. Unfortunately, his rou- 
tine prevents multitasking, with or without 
juggler(er,MultiFinder). It would be better to call SystemTask, 
to keep DA’s multitasking, and GetNextEvent to keep back- 
ground applications running. (Apple says that Systemtask is 
redundant under the Multifinder environment, but it’s easier just 
to call it than to check your environment.) I also think a key 
should be able to cancel the “about.” 


while (true) ( 
SystemTask(); /* keep clock ticking */ 
if (GetNextEvent(mDownMask | keyDownMask, &event)) 
break; 


If you prefer that the click which cancels the “about” be 


passed on to the appropriate program (remember the Mac has ` 
always multitasked —the user could be clicking in а desk 


accessory window to activate it), you can use something like the 
following: 


whileC!EventAvail(keyDownMask | auto =KeyMask | 
&Event )) 
SystemTask(); 
/*Remove mouseDown if in our window */ 
if Cevent. what --mouseDown) 
GlobalToLocal(&event . where); 
if (PtInRectCevent . where, &window- por tRect)) ( 
GetNextEvent (mDownMask,&event);  /*swallow event*/ 


mDownMesk, 


) 


This code comes from my desk accessories, which have 
“transparent” title windows. I call them transparent because you 
can just start typing or mousing without having to actively cancel 
the window— events pass right through. 


Volume 4 Number 4 
But Can It Do Columns? 


For several years, I have been interested in a relational 
DataBase application that keeps track of families and family 
members. I started out on an Apple II, using various DataBase 
products, whose names now escape me, to keep track of Church 
membership lists. Such an application is relational since you 
must track both the family information, and the member informa- 
tion for each member that is linked to that family. Since the Mac 
came out, I have tried various Mac products and have learned a 
lot about the problem of real world processing on the Mac. 

One thing I have discovered is that nearly every Macintosh 
DataBase is incapable of formatting a report of families and 
family members in the same double column format we use for 
MacTutor, with a hairline box around the page and a line down 
the middle. The problem is the products cannot determine how 
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many members are іп each family and how many families will fit 
in the column before moving to the top of the next column. SoI 
offer this DataBase challenge to any Macintosh DataBase prod- 
uct to see if they can create such a report. The winning product 
gets a free ad in MacTutor and a glowing editorial review. Here 
are my results so far. 

I first tried Helix. However, I quickly became buried in icons 
and gave up after a few days. Then I tried MacLion. But they 
went out of business before I even got started. Next came 
FileMaker. Although this is a flat DataBase, I was able to 
accomplish the goal by setting up the file with both the family and 
members of family combined into asingle record foreach family. 
When I needed reports dealing only with members, I used a 
program written in Basic to “flatten” the DataBase and extract the 
members without the family information. The very good export 
and import functions of Filemaker make nearly anything pos- 
sible. By placing the family report in Pagemaker, I was able to 
format it in columns. However, all this “pre-processing” got 
tiring after a few months, so I moved on. 

Next came Omni 3 Plus. However, it soon became apparent 
that the relational aspect of Omni 3 had been tacked on to what 
was once a flat DataBase product, so that working with multiple 
relations between files was very difficult and not at all obvious. 
Although I was told there is a technical note for programming 
Omni 3 to format in columns from a relational DataBase, the 
complexity of the whole thing discouraged me and I gave up on 
it. 

My most recent attempt has been with Borland's Reflex 
Plus. As I reported in a recent issue of MacTutor, Reflex Plus can 
solve the formatted double column report requirement, at least so 
Ithought! Reflex Plus is particularly easy and nice when it comes 
to setting up multiple related files and anything can be quickly 
changedatany time. I love it! Which is why Iam so frustrated that 
itcan'tformata page in double columns correctly. Oh you can set 
up the necessary calculations to group the families and members 
into a double column listing, but the page break option is brain 
damaged and can't figure out when to move to the top of the next 
page when using two independent repeating collections. As a 
result of this bug, you can't keep the family members grouped 
together withouta break at the bottom of each page. And because 
the export function is also brain damaged, you can't export a 
report with nested repeating collections into Pagemaker and 
format the double columns there! So you are just stuck! So close, 
yet so far! (It also lacks the ability to make the box around the 
page and line down the middle and have them repeat on each 
page!) 

That leaves dBase Mac and 4th Dimension as our next 
candidates. Stay tuned! 


Mouse-up Problems 

Delmer A. Johnson 

Castle Rock, CO 

A few weeks ago I encountered a problem similar to the one 
described in Mike Steiner's Mousehole Report posting. I 
couldn't get icons in the finder to open when I double clicked. I 
could select them with a single or double-click and open them 
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using the File menu or a command key. I discovered that the 
problem stemmed from another program which masked out 
mouse-up events. Evidently this is what the finder looks for 
when the user double-clicks on an icon. 

Inside Macintosh II-70 warns against using SetEventMask 
for any purpose other than enabling key-up events. Unfortu- 
nately this advice is not heeded in the original edition of Macin- 
tosh Revealed vol. II, where mouse-up events are disabled (p. 
26). Thenexttime this problem arises, try writing a short program 
calling SetEventMask with EveryEvent. [I've also seen this 
problem. Thanks for finding out what causes it. -Ed] 

Changing the subject, I would appreciate an article explain- 
ing how to display a text file longer than 32k using Textedit. Can 
a person connect several Text Edit records together? 

Cricket Graph Data From Basic 

Steven Leach 

Santa Clara, CA 

I greatly enjoy MacTutor, and have written for your maga- 
zine several times, but I must take exception to the article “Тһе 
Workstation Mac" by Paul Zarchan in the February 1988 issue. 

Besides needing a spelling checker, he must not be very 
familiar with MS BASIC on the Macintosh™ , since I have been 
writing Cricket Graph™ compatible files for as long as the 
product has been commercially available. They specifically 
included a section of pascal code to write the tab delineated files, 
which was extremely simple to write in BASIC as well. When the 
1.1 version of Cricket Graph became available, I did find that my 
BASIC program had to be modified because of the tendency of 
the new version to treat the leading space in the BASIC file string 
for the negative sign as an alpha character rather than a numeric 
character. This problem was easily fixed using the print using 
statement in BASIC. 

When my data files became too large to load quickly using 
the tab delineated format, I simply called up Cricket and they 
kindly sent me a single page description of the fast file format. 
This format I have incorporated into all my BASIC diagrams, 
some of which have been available commercially and as share- 
ware for some time. 

I have included honest-to-gosh subroutines which can be 
used for exactly these purposes. So you can see that there is no 
problem in writing Cricket Graph compatible files. It is this type 
of misunderstanding and lack of curiosity that has relegated 
BASIC and FORTRAN to the "engineering" community, or to 
the "toy" factory. I personally program in Pascal, С, FORTRAN 
or BASIC which ever will do the job more simply, quickly and 
efficiently, although with the interpreter, compiler combination 
it is becoming tougher to justify not using BASIC when I don't 
need special data structures. 


LIBRARY "MS Tools" 
"This is just a sample routine that fills an erray 
‘Saves it to Disk аз а Cricket Graph ™ file 
' end then retrieves data and displays it on the screen 
N.col$ 25 
DIM test.dete(N.co1$, 10), test. tit1e$(N.co18) 
RESTORE 
FOR indx$ - 0 TO М.со1% 
READ test.title$Cindx$) 
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МЕХТ 

DATA “Sample 0”, “Запр1е 1","Semple 2", “Sample 3", “Sample 

4" *ЗАтр1е 5" 

FOR cindx$ = Ø TO М.со1% 
FOR rindx$ = Ø TO UBOUND(test.data, 2) 

test.data(cindxS,rindx$) = rindx%+ 100*cindx% 

NEXT 

NEXT 

file.name$ = FILES$CO, "Nene for File ?") 

IF LENCfile.name$) < 5 THEN END 


CALL seve.Cricket.taebCtest .detaO, test. tit1e$O, N.co1$, 
file.name$) 

CLS 

ERASE test.data, test. title$ 

DIM test.data(N.col%, 10), test. title$(N.col%) 


CALL 
open.cricket. tab(test data(), test. title$(),N.cols, file.name$) 
FOR cindx$ = Ø ТО М.со1% 
PRINT test. title$Ccindx%) 
FOR rindx% = Ø TO UBOUND(test.data, 2) 
PRINT test.data(cindxS,rindx$2,cindx$,rindx$ 
NEXT 
NEXT 
END 


* This subroutine reads in the Data ffrom а Cricket Graph™ 
Fast Format file 
SUB Open.CricketCarray(2), array. tit1e$C DD, N.co1$, f ile. name$) 
STATIC 
watch% = 4 
changecursor watch% 
OPEN file.name$ FOR INPUT AS 41 


tmp% = ASCCINPUTÉCI, 122 
tmp% = ASCCINPUTÉCI, 122 
IF tmp% <> N.col%+1 THEN 
INI TCURSOR 
msg$ = "This«file is not compatible with this Date 
Array” 
CALL errormsg(msg$) 
EXIT SUB 
END IF 
FOR indx% = Ø TO М.со1% 
tmp% = ASCCINPUT$C1, 1)) 
array. title$Cindx®) = INPUT$Ctmp$, 1) 
IF tmp% < 15 THEN tmp$ = INPUT$C 15-tmp%, 1) 


tmp% = 256*ASCCINPUT$C 1, 1)) 
t.col% = tmp%+ASCCINPUT$C 1, 122 
count = 0 

indx2% = 0 


WHILE count$ < t.co1$ 
LINE INPUT #1, tnp$ 
count% = count% + LEN(tmp$)+1 
arreyCindx$, indx2%) = VALCtmp$) 
indx28 = indx2% +1 
МЕМО 
МЕХТ 
CLOSE 81 
ЕМ) 5/8 


'* This subroutine writes the array as а Cricket graph™ Fast 
format file 
SUB Save .CricketCarray(2), array. title$C D, N.co18,f ile. nene) 
STATIC 

watch’ = 4 

N.pts$ = UBOUNDCerray, 2) 

changecursor watch# 

OPEN file.name$ FOR OUTPUT AS 81 


tmp% = М.со1%%1 


{лр# = INTCtnp$/ 16) 
PRINT #1, CHRSCtmpS); 


698 


tmp% = N.col$-16*tmpi*1 
PRINT *1,CHR$(tmp%); 


FOR indx$ = 0 TO М.со1% 
IF LENCarray. title$Cindx%)) = Ø THEN 
array. title$Cindx) = 47“ 
IF LENCarray.title$Cindx%)) < 15 THEN 
PRINT #1,CHRECLENCarray. 11116 indx%))); 
PRINT #1,array.title$¢ indx%); 
FOR indx2% = LENCarray.title$Cindx%))+1 ТО 14 
PRINT 81,СНВ%0); 
NEXT 
PRINT #1, CHR$C1); 
ELSE 
PRINT #1,CHR$C15); 
PRINT *1,LEFT$Carray. title$Cindx%), 15); 
END IF 
tmp = 12*(N.pts$*1) 
tmp1 = INTC tmp/256) 
PRINT #1,CHR$Ctmp 1); 
tmp 1 = tmp-256* tmp 1 
PRINT #1,CHR$Ctmp 1); 
FOR indx2% = Ø TO N.pts% 
PRINT #1, USING“##, titi 7^7 ^; CSNGCerragCindx$, 
indx2%)) 
NEXT 
NEXT 
CLOSE 81 


NAME file.name$ AS file.name$ , "STWK^ 
setCreate file.name$ , “CGRF” 
END SUB 


SUB errormsg С msg$ ) STATIC 
win = WINDOWCO) 
PRINT CHR$CT 
IF win - 4 THEN 
PRINT^ THERE ARE TOO MANY OUTPUT WINDOWS OPEN TO OUPUT 


MENU RESET 
END 
END IF 
WINDOW жіп+ 1, "ERROR WINDOW’, (10, 1002- (450,210), -4 
PRINT msg$ 
default 5,”0К”,50,50,80,80 
WHILE DIALOGCO) <> 1 AND DIALOGCOD € 6 : WEND 


BUTTON CLOSE 5 
WINDOW CLOSE С win+1 ) 
END SUB 


'* This subroutine save the Array as a Cricket Graph 
Delimited Format 
“ This is old Code I used to use this yeers ago 
SUB save Cricket. tabCarray(),array.title$(),N.col8,file.name$) 
STATIC 
watch® = 4 
ttab$ = CHR$CO) 
N.pts$ = UBOUNDCerray, 2) 
OPEN file.name$ FOR OUTPUT AS 81 
PRINT 81,7%” 
FOR indx$ = 0 TO N.col%-1 ` 
PRINT #1, arrau.title$Cindx%);ttab$; 
МЕХТ 
PRINT #1, erray.title$CN.co18) 
FOR rindx$ = Ø TO N.pts% 
FOR сіпах = 0 TO N.col% -1 
PRINT 8#1,USING?## snn... ^ arrau(cindx$, rindx%); 
PRINT *1,ttebf; 
NEXT 
PRINT #1,USING?”88  s:88^ ^*^^ аггау(М.с01%, rindx$) 
NEXT | 


@ The Definitive MacTutor, Vol. 4 


CLOSE #1 
МАМЕ file.name$ AS f ile.name$, “CGTX” 
setCreate file.name$, “СОЮҒ” 

END SUB 


‘ this routine reads a Cricket Graph Tab delimited format 
from the Disk 
SUB open.cricket. tabCarray(), array. title$C),N.col%,file.name$) 
STATIC 
watch = 4 
changecursor watch% 
N.pts$ = UBOUNDCarray, 2) 
ttab$ = CHR$CO) 
OPEN file.name$ FOR INPUT AS 81 
INPUT #1, tmp$ 
IF tmp$ <> “%” THEN 
msg$ = “This file is not compatible with this 
program” 
CALL errormsg(msg$) 
EXIT SUB 
END IF 


LINE INPUT 81, tmp$ 

cindx% = Ø 

tmp% = INSTRCtmp$, ttab$) 

WHILE tmp$ > 0 
array. title$Ccindx&) = LEFT$Ctnp$, tmp%) 
tmp$ = RIGHT$C tmp$, LENCtmp$ )- tmp3) 
tmp% = INSTRCtmp$, ttab$) 
cindx$ = cindx%+1 

WEND 

array.title$Ccindx%) = tmp$ 

М.с01% = cindx£ 


FOR rindx% = Ø TO N.pts$ 

LINE INPUT #1, tmp$ 

FOR cindx% = 0 TO N.col%-1 
tmp% = INSTRCtmp$, ttab$) 
array(cindx%,rindx%) =VALC LEFT$C tmp$, tmp%)) 
tmp$ = RIGHTÉCtnp$, LENCtmp$2- tmp) 

NEXT 

array(N.col%,rindx%) = VALCtmp$) 

T 


END SUB 
SUB default CBUTTONIDS, Title$,Left%, Top%, Right%, Bottoms) 
STATIC 
DIM R&C3) 
BUTTON BUTTONIDS, 1, Title$, (егі, Top$2- (Right, Bottom), 1 


setRect R$(0),Lef t&-3, Top&-3, Right&+3, Bottom%+3 
PENSIZE 2,2 

CALL FRAMEROUNDRECTCVARPTRCRECO), 16, 16) 
PENSIZE 1, 1 

ERASE R$ 

tmp = FRECO) 
END SUB 


Finding The Area Of A Region іп С 

James Plamondon 

Albuquerque, NM 

Ireceived my MacTutor today, and was delighted with it, as 
always (even if my article on random numbers still languishes on 
the back burner). I was particularly interested in the article 
Regions with Aztec С in the C Workshop column [October '87, 
v3 n10 p27-32]. 

The article was concerned, in part, with estimating the area 
of a given Quickdraw region. The authors accomplished this 
with a function, "countpix()." Countpix() considered each pixel 
іп theregion's enclosing rectangle, and determined whether each 
fell inside or outside the region in question. 
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This, to use the authors' own words, is a brutal kludge. The 
authors intended to find the areas of regions which had been 
drawn freehand; accuracy can hardly be at a premium. Further, 
the authors state repeatedly that they are "estimating" the area of 
the region — so why work too hard at an estimation? 

No "assembly-language optimization" willrescue an ineffi- 
cient algorithm from inefficiency; it will just waste time faster. 
A more appropriate algorithm would be one based on a probabil- 
istic estimation of the area of the region, based on a random 
sample of points in its enclosing rectangle. The number of points 
sampled could be very large (hundreds) and still be only a small 
percentage of the total number of pixels in a large region. 

Consider a region bounded by a rectangle with its top-left 
vertex at (l, t) and its bottom-right vertex at (r, b). Assume a 
function (GetIntURand()) which would return a uniformly-dis- 
tributed pseudo-random short integer in the range ПІ, г) or [t, b). 
We can re-write countpix() to return a 32-bit integer (a C long 
int), which gives an estimate of the area of the region in pixels: 


long countpix(rh) 
rgnHandle rh; 


Point p; 
short i, t, 1, b, г; 
long count; 


t = (*rh)->rgnbbox.a. top; 

1 = (*rh)->rgnbbox.a. left; 

b = (*rh)- rgnbbox.8.bottom; 

г = (*rh)-?rgnbbox.a.right; 

for Ci = 0; i < ММ.РТЅ; i++) ( 


v = GetIntURand(t, b); 
h = GetIntURand(1, г); 
f CPtInRgnC&p, rh)) 
count**; 


return(Ccount * (b - t) * (г - 12) / NUM. PTS); 


/* end of countpix() */ 


NUM PTS will determine the accuracy of the estimation. It 
may be either a ‘#defined’ constant or a variable, proportional to 
the area of the enclosing rectangle (or the length of one side). In 
both cases, the accuracy of the estimation will vary with the 
density of the region (ie., how fully it fills its enclosing rec- 
tangle). If NUM, PTS is a constant, the accuracy of the estima- 
tion will also vary with the size of the region. 

This method is not as accurate as the method proposed by the 
authors. However, it is much more appropriate for their stated 
desire, it is much faster, and it, too, is amenable to assembly- 
language optimization. 

XCMD's And XFCN's With Non-MPW 

Steve Roti 

Portland, OR 

Іп response to Danny Goodman's call for more information 
on writing XCMD's and XFCN's with non-MPW compilers 
(reported in Joel West' s column, December '87), Iam submitting 
my comments on using Consulair's MacC version 5.0 for this 
purpose. 

First, grab the include file “HyperXCmd.h” from the disk 
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supplied with the HyperCard Technical Reference Package from 
АРРА. This file contains the definition of the XCmdBlock struc- 
ture used for passing information between HyperCard and the 
XCMD. The C source file must have a typedef to account for the 
type Boolean used in XCmdBlock. The following C code shows 
how to set up the source file. 


8Options +Z 

typedef char Boolean; 

include «HyperXCmd.h» 

pascal void mainCperemPtr) 
XCmdBlockPtr paramPtr ; 


/* body of ХОМО */ 
) 

The only real surprise here is that the function name must бе 
“main” rather than the actual name of the XCMD (otherwise the 
linker will moan about not finding the label main"). The other 
difference is that I was not able to get the include file 
“XCmdGlue.inc.c” to compile in MacC, so I don’t include it at 
the end of the source file. The callback routines should be able 
to be called using the same approach as in Pascal (procedure 
DoJsr), but I haven’t had the need to call any of them yet since the 
input parameters and return value can be accessed directly from 
the XCmdBlock structure. 

The following Link Control File shows how to link the 
XCMD. 

/Output_XCMD 
[Туре ‘RSRC’ 
XCMD 

Standard Library 
/End 

The name of the compiled file containing the XCMD must 
precede the Standard Library file so that the XCMD code will be 
the first thing in the resulting segment. After compiling and 
linking, fire up ResEdit and open the linked file, which will 
contain three CODE resources. Open the CODE resource with 
ID=1, select from address 00000004 to the end (this will elimi- 
nate the four header bytes from the segment), and copy the 
selection to the clipboard. Close the linked file and open the stack 
that will contain the XCMD. Create anew XCMD resource and 
paste the code from the clipboard into it. Choose the menu item 
Get Info for the new XCMD, type in the exact name of the 
XCMD, and check the “Purgeable” box. Save the changes to the 
stack and quit ResEdit. 

Finally, a working XCMD! (You did code it correctly didn't 
you?) Note: everything said here applies to XFCN’s as well. 


New Version Of Shift Mod Patch 

Andy Voelker 

Long Beach, CA 

Here is a new version of the Shift Mod Patch that you 
published in the September, 1987, issue. This version will work 
with Desk Accessories; the previous version did not. 

The ShiftMod Patch in the September, 1987, issue of Mac- 
Tutor didn’t work properly for desk accessories. Here is a patch 
to the original code that will fix the problem. It puts a prologue 
patch on. SystemEvent that uses the same code as our _GetNex- 
tEvent patch to modify keyDown and autoKey events if both the 
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Caps Lock and Shift Key are held down at the same time (in 
which case it will return a lower case letter). 

This modification to the patch is in two parts. The new code 
is surrounded by comments of asterisks. I have given a line or two 
of the original code on either side of the modifications so youcan 
find where to put the modifications in the original code. 

First modification: during the installation part that patches 
_GetNextEvent. Add some code to patch _SystemEvent just 
before the call to BlockMove: 


/* set the trap address to the space we 
* just got in the system heap. */ 
move 8GetNextEvent ,Dd 
_SetTrapAddress 


ЖЖЖЖ / 
define SystemEvent ØxA9B2 


/* set up the address of the SystemEvent 
x JMP instruction */ 
move *SustemEvent, 00 


_GetTrapAddress 
lea e6sysEventAddr, A1 
томе. 1 А0,(А1) 


/* patch SystemEvent */ 

move tSygstemEvent,DO 
/* calculate the after-move address of 
х the _SystemEvent patch */ 

lea @newSysEvent, Ad 


lea @first,Al 
Suba.| А1,А0 
adda.1  (SP2,A0 
_SetTrapAddress 


ЫЫ А ы / 


/* now move it into place */ 
lea ef irst, A0 


move.] (SP)+,A1 
move.1 03,00 
-BlockMove 


Second modification: the patch to _SystemEvent. Put it after the 
patch to GetNextEvent, but before the label @last. 


@eventPtrdc. 18 


/ЖЖЖЖЖЖЖЖЖЕ ЖЕ ЖЕ EER EEE AEA EERE / 
"define RIS 0х4ЕТ5 


@newSysEvent 
lea @patchExit, Ад 
move 8RTS,CA0) 
bsr 6tai Patch 
lea @patchExit, Аб 
move RUMP , CAD) 
dc JMP 
@sysEventAddr 
nopb ~ 


ЖЖЖЖЖЖЕЖЖЖЕЖ ЖЖ АХА ХХХ ХАХ EKER EX EX / 
elast 
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Multitasking Homework 

Mathew Snyder 

South Bend, IN 

I am an undergrad at Notre Dame. I am invoved in a 
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research project in which we аге constructing а communi- 
cation facility similar to TCP/IP. For this project. I have been 
required to port a multitasking "operating system" (really an 
operating system enhancement) to the Mac. 

The operating system kernel and the processes which use it 
run in the background. The technique I use to make all the code 
for the system remain resident is a little underhanded, and I 
would like to know if there is an easier way it could have been 
done. The current technique involves moving the code in the 
application heap into the system heap. 

The tricky part which is most underhanded, is convincing 
the Mac's memory manager that the space now at the top of the 
system heap should be considered an allocated and locked 
block. I do it by directly manipulating the data base of the 
memory manager. 

I considered allocating a block in the system heap and 
loading in the code I want to stay resident by hand, but the code 
is compiled and linked using an ordinary language system, and 
Ididn't wantto mess with allocating stack space, global variable 
space, resolving references, building a jump table, etc. 

Is there a simple way to instruct the segment loader to fix 
things such that an application gets loaded into the system heap? 
(I suspect not.) 

Iam aware that it is possible to have your resourses loaded 
into Ше system heap. What would happen if I loaded the 
resources of interest using the resource manager? Would refer- 
ences be resolved, etc.? [Messing around with the system heap 
is a Macintosh no-no. You might consider Lightspeed Pascal 
and the Mach2 Forth system. Both of these products use a kind 
of application specific multitasking that manages to co-exist 
with the Mac OS, but not without a lot of work and bug fixing. 
The Resource Manager cannot resolve code references in 
seperate code resources. It is not a linker. -Ed] 

Scanning for specific keys 

Warren P. Michelsen 

Page, AZ 

Just wanted to drop a quick note your way in response to a 
letter in the March issue regarding scanning for a keypress. Ihad 
the same problem about a year ago and experimented enough 
with LS Pascal to satisfy my needs. 

I'm just a little ashamed to say that I did not document 
everthing I found out regarding how LSP treats a keyMap and 
I don’t have the time right now to reverse engineer the enclosed 
source code. Once I figured out how it works I thought I'd never 
forget. 

Obviously, my routine(s) could be modified to accept a 
passed parameter to check for any key. I didn’t happen to need 
that feature at the time. In fact, I’ve never had the need to check 
more than the option key. Oh, well. I hope someone finds it 
useful. [Note that this unit does not handle all combinations of 
keys if both the shift and command key are held down together. 
As presented here, it correctly detects a single function key held 
down in conjunction with a normal key. -Ed] 


UNIT ModKeys; 
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INTERFACE 


VAR 
MyKeys : KeyMap; 


FUNCTION CommandIsDown : Boolean; 

( check the Command key to see if pressed . } 
FUNCTION OptionIsDown : Boolean; 

( Check the Option key to see if pressed .} 
FUNCTION CapsIsDown : Boolean; 

( Check the Caps Lock key to see if pressed . ) 
FUNCTION ShiftIsDown : Boolean; 

( Check the Shift key to see if pressed . ) 


“bass aa Чар ны 
FUNCTION CommandIsDown; 
BEGIN 


CommandIsDown := False; 
GetKeys(MyKeys); 
IF BitTstC@Mykeys{1], 16) THEN (16 = Command key) 
CommendIsDown := True; 
END; 


(——_—______———__} 
FUNCTION OptionIsDown; 
BEGIN 


OptionIsDown := False; 
GetKeys(MyKeys); 
IF BitTstC@MyKeys[1], 29) THEN (29 = Option key} 
OptionIsDown := True; 
END; 


оа---------- 


FUNCTION CapsIsDown; 
BEGIN 


CepsIsDown :- False; 
GetKeys(MyKeys); 
IF BitTstC@Mykeys[1], 30) THEN (30 = CapsLock key) 
CapsIsDown := True; 
END; 


с---- 


FUNCTION ShiftIsDown; 
BEGIN 


ShiftIsDown := False; 

GetKeys(MyKeys); 

IF BitTstCeMyKeyst 1], 31) THEN (31 = Shift key} 
ShiftIsDown := True; 


END; ) 

END. (of unit ) 
Background Load Task 
Erny Tontlinger 


Steinfort, Luxemburg 

Here are some comments about the article *A Background 
Task for Measuring Load" from Peter Korn in the C Workshop 
part of MacTutor, March 1988. I found the article and the 
program very interesting because I wanted to become more 
familiar with MultiFinder programming. But there was one bug 
and two details where I cannot understand why they were 
programmed like that (especially from someone working for 
Apple Computer). 

In the function doLoad(), the current GrafPort must be 
saved, the GrafPort of the loadWindow must be set before 
drawing the bar graph, then the saved GrafPort must be restored. 
Otherwise the program will bomb if you try to open a disk 
accessory while the program is in the front. [This is not true. The 
program runs just fine with desk accessories, which are taken 
care of while under MultiFinder in the DA layer. If you are not 
under MultiFinder, it is possible that some flakey DA' s might 
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cause а problem, but the program doesn't execute unless 
MultiFinder is active. -Ed] 

Why that discussion about coding an absolute filename in 
the program? Тһе program line in question ( 
OpenResFile(“pGLA appl”); ) is completely superfluous 
because the resource fork of the application is opened automati- 
cally when the program is launched! [See Peter Korn’ sresponse 
to this question below. -Ed] 

The WaitNexxtEvent( function can be coded much sim- 
pler in LightSpeedC (I’m using version 2.11) as follows: 


"define WaitNextEventCeventMask, theEvent, timeOut, mouse- 
Вох )\ 

_WaitNextEvent(CeventMask), (theEvent), (time0ut), 
(mouseBox)) 

Pascal short_WaitNextEvent()=0xA860; 

Notes on Background Load Task 

Peter Korn 

Berkeley, CA 

I was very happy to see my article, System Load Under 
MultiFinder, published. Having seen and learned from the 
many fine articles in your publication I was very happy to make 
a contribution of my own. In fact, I'm working on a few other 
subjects (XCMDs for HyperCard, etc.) that I hope to turn into 
articles in the near future. 

I was saddened to see the article intimating that I am an 
employee of Apple Computer. While it is true I work there full 
time, I do so as a contractor, which isn't quite the same thing as 
an employee. Though this distinction isn't terribly important 
one (the content of the article is just as valid either way), I would 
like to set the record straight. 

While we're on the subject of record-straight setting, I 
should also mention that the current version of UW (Unix 
Windows, by John Brunner), version 4.2, now handles Up- 
dateEvents purely as UpdateEvents, and doesn't do anything 
else with them. In fact, UW 4.2 is fully MultiFinder friendly to 
the best of my knowledge. 

One bit of code that perhaps should have been in GLA but 
didn’t make it into the copy I sent you is a test for MultiFinder's 
“Temporary Memory Calls". While this isn't strictly necessary 
when running under System 4.2 (where, if WNEQ is imple- 
mented, so is MFMaxMemY() and its associated calls), it may 
become a problem if Apple ever seperates the two (by, say, 
putting WNE() into the System proper, but leaving 
МЕМахМет() and its bretheren as part of MultiFinder only). In 
thatcase, GLA would run even with no MultiFinder present, but 
crash the moment МЕМахМето is called. Probably the best 
way to implement this would be to set a boolean to true if the 
Temporary Memory calls were available, and then simply 
disable the “Compress Juggler RAM" menultem if that boolean 
were false: 


define ^ JugglDispatchx8F 
"define —UnImplTrepNum Ox9F 
"define SwitchPtr (long *2(0x282) 
boolean — tempRAMhere; 
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tempRAMhere = (((*SwitchPtr == Ø) || CXSwitchPtr == -1)) 
&& CtheWorld.machineType >= 0 ) && 
(NGetTrapAddress(Jugg Dispatch, ToolTrap) != 
NGetTrapAddress(UnImp1TrapNum, ToolTrap))); 
o 


o 


o 
if (!tempRAMhere) 
Disableltem(conf igureMenu, 3); 


Lastly, your comments on page 41 “...Peter does another 
thing we don't recommend: he opens а specific resource file by 
file name...” is made a little hastily. In LightSpeed C, one 
normally puts in the line: 

“OpenResF i 1e(“\pResourcesF i leName.rsrc” )“, 

which is a queue to Lightspeed C to go and look for the 
resources in that file when LightSpeed C launches the program 
directly from itself. This is also a way of informing LightSpeed 
C where it should go to find the resource file it will use when it 
links the file. This line is in there for development purposes, and 
is normally ignored when the program is compiled and run (so 
sayeth the LightSpeed C manual). In fact, the original source 
code that I sent you contained the line: 

“OpenResFileC”\pLoad Average .гѕгс* )*, 

and not 

“OpenResFileC“\pGLA арр1”)”, 

which was how you apparently edited it to be before 
printing. Had you left it as I sent it to you, you would have 
probably realized that it couldn’t have been a hard coded name, 
as the program's name is “GLA” and not "Load Average.rsrc”’. 
Apparently in the rush to publish the March issue you missed 
this detail. [1 was unaware LS С works in this manner. They 
should change it to work like their LS Pascal product, which 
uses a dialog boxrather than a code hack to deal with resources. 
Sorry. -Ed] 

Folder Helrarchies & User Interface 

David Dunham 

Goleta, CA | 

Interesting to see the user interface letters in MacTutor. 
The interface is an all-too-often neglected part about writing a 
program. A lot of people have ideas thatI think are impractical 
(of course, the only real way to tell is to try them with real people, 
in real situations). For example, Ted Johnson's idea for folder 
hierarchies which run up sounds nice at first, but it means menus 
work two different ways —normally you click on the menu and 
drag down. Now you'd have some menus that you drag up to 
operate. (Yes, pop-up menus as implemented in the newish 
PopupMenuSelect( trap also violate the one-way-to-use-a- 
menu principle. Does this suggest they should be avoided 
whenever possible?) But this isa philisophical point, and I could 
be wrong. Less subjectively, the item appears at the top of the 
dialog. There is a lot more space for a long hierarchy if the list 
runs from top to bottom, instead of bottom to top (it could easily 
bump into the menubar or top of the screen). Perhaps the pop- 
up should have been put under the scrolling list, but that would 
probably have conflicted with existing dialogs. If Apple had | 
designed the original Mac with HFS in mind ( from the begin- 
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ning I wondered why they didn't), Johnson's idea would be 
good. With the existing Mac, it's not compatable with the 
common way of doing things, and its advantages don't seem to 
outweigh this disadvantage. 

How to Animate a Watch Cursor 

The Midnight Hacker 

Atlanta, GA 

Responding to some comments made in the March Mouse- 
hole Report... 

Regarding Consulair's 1) lack of technical support, 2) less 
than a full Toolbox (support for IM V. 5 calls), and 3) Mac C Jr.; 
Consulair Mac C has had one foot in the grave for over a year 
now. Mac CJr. is the original Mac C without library sources or 
technical support. Competition from Lightspeed C and MPW 
have eaten Consulair's lunch, so it is most unlikely the product 
will ever be upgraded again. 

Mac C Jr. is a last gasp attempt to squeeze $$$ off the 
bottom of the market (as the original Mac C, the first C 
development system for the Mac (and very pricey at over $400), 
was meant to cream $$$ off the top). Ditto Consulair 68000 
assembler. Simple economics: the end of a product life cycle 
due to overwhelming competition. Mac C is a solid product, but 
LightSpeed is THE Mac Code Yuppie compiler, and MPW has 
Apple's name on it. 

Speaking of Lightspeed C... Version 3.0 is due in April- 
May. Anyone who bought v2.15 after February 1 recieves a free 
upgrade. The new version has a source-level debugger (ala LS 
Pascal), bug fixes, improved editor, and much improved docu- 
mentation. 

FullWrite Professional may be a memory hog (it requires a 
Meg for itself to run), but it is going to give Word and Page- 
Maker both a serious run for the money. FullWrite is one 
amazing piece of software. The only shame is the early 
advertisements that made it look like a vaporware hype (which 
it was at the time). The boys of Ann Arbor (er, Ashton-Tate) 
made the tough but correct decision not to release FullWrite 
until it was done (remember Word 3.00?!). Better to eat crow 
up front than have the magazine reviewers sink your product 
once it hits the streets. 

Anamated cursers. Do it yourself. Keep track of what 
cursor is active using a global (curr cursor below). 


8define WATCH! ?  /*cursor resource number of 9 o'clock */ 
/* WATCHes are consecutively numbered cursor resources */ 
"def ine WATCH8 ? /* cursor resource number of 9:50 watch */ 
Bdef ine NEXTWATCH 10 /* ticks between watch changes */ 
define EVENTFLUSH OxFFFFFFFF 


(global) 

long watchtick; 
changed* / 

short curr.cursor; 
CursHandle watch[8]; 


/*the last TickCount the watch was 


/*current cursor (resource number)*/ 
/*handle to watches*/ 


(local) 
long now /*be here..*/ 
if Ccurr-cursor >= WATCH1) 


FlushEventsCEVENTFLUSH,NIL); /* no user event build-up */ 
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now = TickCount C); 
watch*/ 
ifCCnow -watcht ick )»=NEXTWATCH) 


/*check if it’s time to change 


watchtick = now; /*new watch indicator*/ 
/*set the cursor to the next watch*/ 
ifCcurr_cursor == WATCH8) curr_cursor = МАТСН1; 
else curr_cursor +t; 


/*show the appropriate watch cursor*/ 
ааа canoe Wet 


) 


It's laughable that someone wants Apple to animate their 
cursor for them. I guess the Magic Toolbox has made us spoiled 
children. If you need an attitude adjustment, try programming 
an MS-DOS boat anchor. That'll animate your cursor! 

Microsoft news: the DOS kids are beavering on their CD- 
ROM Reference Set DA for the Mac (similar to the Bookshelf 
Reference CD-ROM currently available for everyone's favorite 
boat anchor). It'll make a great Christmas Gift (if the schedule 
doesn't slip). 

MultiFinder Bug In the Background? 

Larry Schmitz 

Athens, GA 

Thank you for your article on the MultiFinder friendly 
Draw Plotter (Feb. 88). It was most useful. There were, 
however, a number of corrections that needed to be made to get 
the program to run. The procedure, *doMessage", was missing 
and the about box and the PICT it contained required some 
redoing. /The doMessage proc was indeed left out, but printed 
in the Marchissue. The code and about Box compile and run as 
printed. -Ed] 

One point that the program did not address was doing 
background processing. I have written a program that runs in the 
background under MultFinder. However, it has one problem 
that I have had to write a clumsy kludge to get around. This 
problem is also exhibited by your program if you set the Can- 
Background bit in the size -1 resource. Perhaps you or one of 
your readers can shed some light on this topic. 

The problem only occurs if WaitNextEvent is called, the 
CanBackgroundbit is set and the application does not have a 
window open. In order to demonstrate the problem using your 
MiltiFinder Friendly Plotter program as an example, do the 
following. First, compile your program (I used LSP 1.11 and 
make the corrections mentioned in the first paragraph). Then 
use ResEdit to set the CanBackground bit. Next, run MultiFin- 
der and launch the Plotter program. Make sure that none of the 
windows from the Plotter program are open. Open a desk 
accessory and then close it so that the Plotter program again 
becomes the front most layer. At this point the Mac will hang 
and must be restarted. In order to get around the problem, I call 
SystemTask/GetNextEvent rather than WaitNextEvent when 
FrontWindow returns nil. Unfortunately, this is not very 
friendly to other background tasks. Whose bug is this? [The plot 
program does indeed hang the Mac under the conditions you 
describe, and the problem does go away if you check for a front 
window before calling WaitNextEvent. There must be some 
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connection between accepting null events as a background task, 
the desk acc. layer manager, and WaitNextEvent expecting to 
find an active window. I can't imagine what that connection is, 
but it seems like either a MultiFinder bug or a bug with the Desk 
Acc. handling under MultiFinder. Peter Korn and Г spent ап 
hour looking into this and we did confirm that his graphic load 
background task shows the same problem, if you remove the 
showWindow command. So there is a high probability this is a 
MultiFinder bug. -Ed] 

Floating Windows in C 

Vincent D. McGarry 

Austin, TX 

In answer to the questions posed by Kenrick Chan and Ajay 
Nath, I have been using the follow code (Aztec C) to "float" 
windows. Calls to DragWindow( cannot be used since it calls 
SelectWindow(). Instead I do some necessary preparation and 
then call DragGrayRRgn() and MoveWindow() directly. Se- 
lectWindow( is never called. The window I want to float is the 
Ghost Window. I have not tried to do this with GrowWindow(). 
All the windows in my application are *noGrowDocPro"s and 
therefore act like the tools palette in FullPaint. I have not done 
this with more than one window “floating” but soon will be since 
my application requires that the active window, being quite 
large on the screen, be behind the several other comparatively 
small windows that accompany it. 


*def ine GHOST бхА84 

*def ine BADMOVE 0Х80008000 
se tupwindows( ) 

( 


WindowPtr *GhostWindow; /* and other declarations */ 
GhostWindow =GHOST 

FloatWindow =GetNewWindow(F loatResID,&F loatRec, - 1); 
*GhostWindow= FloetWindow; 

ShowW indow(F loatWindow); 

Br ingToFront(FloatWindow); 


| /* rest of setupwindows ы 
mousedownt( ) 
/* local declarations and other processing */ 


cese inDrag: 
Screen = screenBits.bounds; 
SetRect(&limitR, 4, 24, Screen.right - 4, Screen.bottom - 
4); 


setRect(&slopR, Screen.left, Screen.top +24, Screen.right, 
Sceen. bottom); 
local_mouse = global. mouse; 
Global ToLocal(&local_mouse 2; 
GetWMgrPortC & wm_port 2; 
windstruck = NewRgn(); 
CopyRgn( (CW indowPeek2wh ichWindow2-?strucRgn, windstruct); 
GetPor tC &savepor t); 
SetPortCwm_port); 
ClipRect(&wm_por t-> por tRect); 
newloc = DragGrayRgn С windstruct, /*new window loc*/ 
pass(global_mouse ), 
&limitR, 
&slopr, 
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0, 
OL ); 
DisposeRgn Cwindstruct); 
if С newloc != BadMove) 
MoveWindowC whichWindow, 
LoWord(newloc)+global_mouse.h - local.mouse.h, 
HiWord(newloc)+global_mouse.v - local.mouse.v, 


FALSE); 
SetPor tCsavePor t); 
InvalRect (&savePort->por tRect); 
break; 
/* other processing x/ 


) 


Floating Windows the Simple Way 

lan McLellan 

Waterloo, Canada 

Here is a way to get a certain window to always stay in front 
of another window. What I tried is pretty sleazy, but it works. In 
my main loop, I put: 

IF FrontWindow © theWindowToStayInFront THEN 


BringToFrontCtheWindowToStayInFront); . 
It seems to keep the "behind" window active, yet puts the 


window (usually a menu window) on top of it. This probably 
breaks a couple of Apple's laws, and I haven't tested it too 
extensively, but I couldn't think of another way to do it. 


Volume 4 Number 6 


[TML has returned to the Mac market with a new version of 
TML Pascal that runs under MPW and supports objects and 
MacApp. This is the first non-APDA product to be available from 
a third party that supports MacApp. This is important because it 
means more widespread availability of MacApp compatible 
МРИ tools than just through АРПА, which enjoys an Apple 
supported monopoly on distribution. Here is an advance look at 
TML Pascal version 3.0, being announced this month at Mac 
Hack in Ann Arbor, Michigan. -Ed] 


TML Pascal v3.0 
Tom Leonard, TML 
Jacksonville, FI. 

Version 3.0of the TML Pascal compiler will be a completely 
new implementation of TML Pascal. The most significant 
change for this product is that it will be converted to operate with 
the Macintosh Programmer's Workshop (MPW) as an MPW 
Tool. 

The following isalistof the major features provided by TML 
Pascal v3.0: 

* Operates within the Macintosh Programmer's Workshop 

* Complete support for Object Pascal 

“ Compiles MacApp 

e Native 68020 and 68881 code generation 

• Conditional compilation 

е Assembly source code output as well as object code output 

• Constant expression evaluation in declarations 

• Performance analyzer 

° Complete integration with other MPW languages includ- 
ing MPW C and Assembler. 

In addition to the Pascal compiler, the product will also ship 
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with a Pascal pretty printer (TMLPasMat) and Pascal cross 
reference tool (TMLPasRef). 

TML Pascal will support the development of any type 
Macintosh program. These include: 

* Desktop applications 

• “Textbook” applications 

* MPW Tool applications 

* Desk accessories 

* Definition procedures (WDEF, MDEF, CDEF, LDEF, 
etc.) 

е FKEY resources 

* INIT resources 

е HyperCard XCMDs and XFCNs 

and more... 

Examples of how to create all of these various types of 
programs are provided with either the TML Pascal product or the 
TML Source Code Library. 

In addition, TML Pascal will provide several MPW “scripts” 
which will implement custom menus and other user interface 
elements to make using the MPW shell easy for the beginning 
programmer. Compiling and executing a program will be as 
simple as selecting the “Compile & Run" command from the 
"TML Pascal" menu. In fact, many users may never find it 
necessary to use other MPW commands to compile and create 
programs. 

External Tool Specification 

Syntax ТМІ Pascal [ option...] [ file...] 

Description Pascal language compiler. 

Input: One or more Pascal program or unit source code text 
files. By convention, Pascal source file names end with the suffix 

Output: Thecompilercan create twotypes of output: MPW 
object code (the default) or MPW assembly source code. The 
Output is written to a file whose name is the input source file name 
with the “о” or “.а” suffix respectively. 

There is no output to standard output. 

Diagnostics: Compile time errors are written to diagnostic 
output. Progress and summary information is also written to 
diagnostic output if requested. 

Status: The following status values are returned to the Shell: 

0 Successful completion 
1 Error in parameters 
2 Compilation halted 

Options: 

-align Align all data items on longword boundaries. 
-asm Compile the source file to assembly source 
output rather than object code. 

-d name- TRUE | FALSE 

Set the compile time variable name to TRUE or 
FALSE 
-i pathname [pathname]... 

Search for include or USES files in the specified 
directories. Multiple -i options may be specified. At 
most 15 directories will be searched. 

-mc68020 Generate code to take advantage of the 
68020 processor. 
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-mc68881 
the 68881 co-processor. 

-0 outName 

Specify the pathname for the generated output file 
(object or assembly). If outName ends with a colon (:), it 
indicates a directory for the output file, whose name is 
then formed by the normal rules. If outName does not 
end with a colon, the output file is written to the file 
named outName. 

-0v Turn on overflow checking. 

-p Output compiler version and progress information 
to diagnostic output. 

x Suppress range checking. 

-t Report compilation time to diagnostic output. 

-u Initialize local and global data to the value $7267. 
Used for debugging. 

-2 Turn off the output of embedded procedure names 
in the object code. This option is equivalent to the ($D-) 
compiler directive. By default, the compiler creates the embed- 

ded procedure names for use by TMON, MacsBug, and 
other debuggers. 


Generate code to take advantage of 


Language 
TML Pascal v3.0 will be a compatible ANS Pascal and 
MPW Pascal compiler. In addition, a significant amount of time 
will also be spent further improving the code quality of generated 
code. Because the current version of TML Pascal is already very 
much compatible with MPW Pascal, no major changes are 
required. The following is a list of the more significant changes 
to be made for TML Pascal v3.0. See the TML Pascal v3.0 
Language Reference Manual for a complete definition of the 
language. 
* Conditional compilation 
° Short circuit boolean operators ( &, 1) 
* Exponentiation operator ( ** ) 
* Identifiers may begin with an underscore 
* Implement the “С” subprogram directive 
* Fully implement Object types 
* Type REAL changed to be equivalent to SINGLE 
° Support 96 bit extended reals for 68881 
“ Support constant expressions where constant literals are 
normally expected 
° Support sets in the range 0..2039 
* Untyped files 
* Type casting between ordinal types of different sizes 
The Trouble With FONDs 
Cliff Joyce 
Northridge, CA 
By the way, I noticed the discussion in a recent MacTutor 
issue regarding the problems with bitmapped fonts behaving 
strangely in applications that use fractional character widths. 
The problem goes back to older versions of the Ғоп/ОА 
Mover Which improperly set bit 14 of the ffFlags word when 
building FOND resources from scratch. This flipped bit tells the 
application that the FOND contains a fractional width table. The 
application then uses ff WTabOff to find the address of the width 


table. But since ffWTabOff is zero іп this case, the application 
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points to the beginning of the FOND—usually causing charac- 
ters to overwrite themselves when being drawn. 

We have removed all FONDs from our World Class Fonts 
collections, and included Font/DA Mover v3.6, which properly 
sets bit 14 of the ffFlags word. 

However, а safer solution might be for programmers to make 
two tests to determine if a FOND contains a fractional width 
table. First test the bitflag, then test ff WTabOff. If ffWTa- 
bOff=0, assume there is no fractional character width table. 

By the way, Font/DA Mover v3.6 now improperly sets bit 15 
of the ffFlags word when creating generic FOND resources 
(unless my Inside Macintosh volume IV is not accurate in 
describing the setting of bit 15). This may be a moot point as 1 
am unaware of any applications that use this bit for anything 
(yet). 

Oh, yes—enclosed is my check for another year's subscrip- 
tion. That's it for now. Keep up the good work... 
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Announcing... 
Steffanie Sheets 

Steve and Patricia Sheets are very, very pleased to announce 
the birth of their daughter, Steffanie Virginia Sheets. Steffanie 
was born Monday May 30, 1988 at 11:55 AM. The blond hair, 
blue eyed girl weighed 6 lbs., 12 oz at birth, while the labor lasted 
just under 6 hours. The mother, the daughter and the panic 
stricken father are enjoying each others company for the next 2 
weeks at home. 

Hope to talk to you all when I get back! [Steve Sheets is a 
contributing editor of MacTutor and responsible for nearly all 
the articles on color and the Mac II in the last year. We wish him 
and his family well. -Ed] 

Credit For Tear-Off Menus 
Mike Bolch 
President, Radius Inc. 

We were flattered by all of the references to the Tear-off 
Menu feature of our Radius Two Page Display in your April, 
1988 C Workshop. This feature is indeed both flashy and useful, 
and greatly appreciated by our customers. 

The primary author of the software, however, is Ted Cohn, 
of the Radius engineering team. I'm sure Ted would be the first 
to acknowledge Andy's advice and support, but I'm equally sure 
that he was chagrined to see all of his work attributed to some- 
body else. Iknow I’m always upset when people confuse me with 
Tom Selleck... 

$50 MatLab & Facelt Revealed 
Dan Катртеіег, FaceWare 
Urbana, IL 

As a developer of a Macintosh programming tool (Facelt — 
see this or a recent issue of MacTutor for ad), I naturally keep a 
close eye on related products and reviews in major Macintosh 
magazines. Unfortunately, many reviewers seem to have had 
limited exposure to the wide range of available Mac program- 
ming tools, and the resulting reviews are full of “Mac-hype”. 

One of the most hype-ridden reviews of recent date was that 
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appearing in the April 26 edition of MacWeek. The 1-page 
review entitled “Prototyper: Build-it-yourself software" might 
have been more appropriately entitled “Ргою-Нуре”. When the 
reviewer finally did address potential problems with the product, 
he abruptly ended the discussion by saying that a call to the 
developers revealed that “all our wishes had already been antici- 
pated". I called MacWeek to find out who this reviewer was 
(maybe we could get him to do an equally naive review of 
Facelt!). Their response was that they really didn’t know much 
about the review (they read it while we talked). 

What's bad about such reviews is that they ultimately do a 
disservice to both the developers and the users (in this case 
programmers). In the above case, for the example, Prototyper 
from SmethersBarnes is a great product for certain types or 
phases of development. The reviewer should have made it clear 
under what circumstances the use of the Prototyper is warranted 
and what its limitations are. In our opinion, it is best suited for 
the first 10-3096 of program development where one is creating 
abasic eventloop, menu handling, and window resources. It can 
generate source code (currently limited to Pascal) to which the 
rest of the program code is added (the 70-90% of a program that 
does something). (Can't you just see those Apple reps carrying 
around a copy of Prototyper to demonstrate that all you have to 
do to write programs on a Mac is point and click! Get real.] 

Thus Prototyper, unlike many other programming tools does 
notrelieve you from having to dig through hundreds or thousands 
of lines of interface-related source code, it just helps you get 
started creating such code. A call to SmethersBarnes not only 
confirmed this overall impression of the limitations of Prototyper 
(they are more open about this on the phone than in their 
advertising), but also resulted in their disclosing a revealing bit 
of information: one of the companies using Prototyper asked for 
a special version which did not generate source code since they 
already had programmers who could do that! Thus it was the 
non-programmers who were being given Prototyper as a means 
to let the programmers know what they wanted in an interface. 
This conflicts with the reviewer's claim that Prototyper was 
"designed primarily for developers". 

This brings us to MacTutor. Although generally a happy 
camper, the recent review of MatLab from Math Works by Paul 
Snively (both from Massachusetts) in the May 1988 issue of 
MacTutor caught my eye. This product retails for $895, but there 
is a competing product called “MacMatLab”, based on the same 
original Fortran program which retails for just $50 [yes, that's an 
$845 difference]. In fact, after reading this review, I find very 
little difference between these products, although no mention of 
MacMatLab is made by Paul in spite of the fact that it has been 
advertised in MacTutor! It is hard to believe that Paul was 
unaware of the existence of MacMatLab. Anyway, before you 
run out and spend a whopping $895 for MatLab, you might want 
to try a $50 version of a very, very similar-functioning program! 

Which raises an interesting question: Why can QED Asso- 
ciates charge just $50 for their version of MatLab? The answer 
is that they used our product, Ғасе (950-9100), to add the Mac 
interface to an existing program. Facelt is a collection of 
preformed resources which can be used by programs created with 


© The Definitive MacTutor, Vol. 4 


almost any language and compiler. It "instantly" adds a Mac 
interface that handles such things as editing of text and pictures, 
file handling, and printing. One copy on disk can even be used 
by multiple programs at the same time. It is well-suited for the 
conversion of existing programs for use on the Mac, and is also 
useful in cases where a programmer does not have the time or 
resources to write every little program he/she creates. In July a 
version will be released which includes "instant" spreadsheet- 
like windows which can be linked to any array in memory. 

So, contrary to what is often heard in MacTutor, there is a 
fast way to add a Mac interface: FaceIt. Moreover, our sample 
programs cover text editing, plotting, drawing, animation, and 
background processing. The current $100 version includes 
sample programs for 10 or more different compilers on 5 disks (ог 
$50 for one compiler on 1 disk). Facelt is not for everyone, but 
if it fits your needs then we are confident that there is no better 
value when it comes to development tools. The biggest criticism 
we get from users is that it should be priced higher so we can 
afford fancier advertising and increase its perceived worth. 
[Translation: Buyers are ignorant, so run only full-page color 
ads full of hype, don't be afraid to charge a ridiculous price, and 
most importantly, always subtract 5 cents from the price before 
putting it in print.] 

Conclusion: Someone needs to take a careful look at the 
range of Mac developers tools and compare them with respect to 
price, ease-of-use, and functionality. There's just too much hype 
out there for the average programmer to see through. [Actually, 
the opposite may be true: there is not nearly enough information 
out there for developers to know what is available. -Ed] 
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Mac Power Supply History Reviewed 
Dr. Ray A. Gaskins 
Hampden-Sydney, VA 

Itcould be argued that 1987 was the year ofthe power supply 
(analog board) problem. Don Ritter, writing in MACazine, 
mentions the power supply in seven out of twelve of his M.U.G. 
WRESTLING columns. MacTutor, in six of its monthly issues, 
devotes more (and useful) words to it than any other publication. 
The Active Window (Boston Computer Society publication) 
mentions something about the power supply in three of its 
monthly issues. Perhaps not surprisingly, MacUser and 
MacWorld mention the power supply in only one issue each. 

The earliest reference to the power board problem that Ihave 
seen is one mentioned by Ritter in MACazine (Jan 87, page 61). 
He references an article by Howard Upchurch which appeared in 
the July/August 1986 issue of Apple Gram. Upchurch blames the 
problem on two underrated capacitors and on the flyback trans- 
former. Other 1986 articles referenced by Ritter are a “bad power 
supply board survey form” in which Apple admits to a power 
board problem with Mac Plus upgrades. However, MACazine 
itself makes no mention of power board problem in 1986 (nor, for 
that matter, do MacUser, MacTutor or MacWorld). 

Apart from recommending the removal of the heavy alumi- 
num RFI shield mounted across the top of the power supply board 
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as a means of increasing air flow and reducing heat, Ritter has 
little to suggest short of suing Apple. Instead he tells an endless 
string of horror stories about multiple power board failures. 

In my own fixed population of just over 100 Macintoshes, I 
have the full range of Macs (1984-1988). I can remember two 
Macs out of this population that seemed like characters out of 
Ritter’s horror stories. In both cases, replacing the video tube 
fixed the problem. Therefore, my advice to anyone whose mac 
eats power boards (say, three boards in six months) would be to 
replace the video tube (along with the third or fourth power 
board). A symptom of this problem is a discoloration due to heat 
of the four-pin connector that connects the video tube to the J1 
connector on the power board and a history of eating power 
boards. 

I believe that there is some truth to the rumor that Apple felt 
that part of the power board problem was due to the procedure 
being used to discharge the video tube - you know, two crossed 
screw drivers. I have lost a couple of power boards because of 
this and began not discharging the video tube for doing routine 
things not involving the power board (e.g., replacing the logic 
board). My failure rate declined. Now there is a neat tool for 
discharging the video tube that meets Apple's approval and I use 
it religiously. 

In the 15 months prior to July 1987, I replaced 13 power 
boards. In the 9 months since then, I have replaced only 4. I 
attribute this to three things: Loy Spurlock, Chuck Rusch, and 
Mysteray. MacTutor published long and detailed letters from 
Loy Spurlock (March 87, page 4) and Chuck Rusch (June 87, 
page 13) concerning the power board problem and what you 
could do about it (short of suing Apple). Mysteray (July 87, page 
17) wrote two long comments in MacTutor's Mousehole Report 
concerning the J1 connector on the power board - why it tended 
to develop a cold solder joint, how to detect it and how to fix it. 
I am grateful to these three people for their words of wisdom. 

Since July 1987, I have had 10 power board problems that, 
prior to reading Spurlock, et. al., would have meant 10 power 
board swaps. However, applying their advice, I was able to save 
6 of these boards by resoldering. The symptoms were varied: 

(a) three had the classic thin vertical white line in the 

center of the screen, 

(b) two had the shakes (screen jitter), occasional spikes 

and expanding/contracting screen, 

(c) three had horizontal lines across the top and/or 

bottom of the screen, and 

(d) two had a faint vertical line just to the left of center. 

Resoldering the four pins of the J1 connector fixed two (a)'s _ 
one (b) and two (c)'s. Resoldering two other joints that appeared 
dull under close inspection fixed the other (b). 

Resoldering had no effect on one of the (a)'s , one of the (c)'s 
noron either of the two (d)'s. (Rumor has it that the faint vertical 
line means that the power supply will fail within six months.) 
Fixing six out of ten power boards by simple resoldering isn't 
bad. These Macsrange from 128K to Mac Pluses. None had fans. 

Using a jewelers eye piece (10X), I also examined the joints 
at J2 (9 pin connector) and 74 (11 pin connector) on each of these 
boards. More often than not, one or two solder joints on each end 
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showed cracks. Resoldering these, although good preventative 
maintenance, is usually not as critical as resoldering the four 
joints at J1. 

I looked at a couple of the replacement power boards and 
noticed that some of the connections had been resoldered by 
hand, including the four pins of the J1 connector. I couldn't tell 
their resoldering from mine. The only difference was that they 
put on a new paper backing with new double-stick pads. If you 
are careful in peeling back the double-stick pad (use a plastic 
video alignment tool with a screw driver blade to help peel it 
back), you won't have much residue to clean off before resold- 
ering and you can restick the pad without applying additional 
glue. 

What caused the cold solder joints? І believe that the 
explanation given by Mysteray (loose video yoke connector) is 
probably correct. Therefore, I always tighten this connector 
whenever I resolder the pins at connector J1. For a thorough 
explanation of this, see Mysteray's comments in MacTutor (July 
87, page 17). 

As far as voiding your warranty is concerned, after 90 days 
you are on your own unless you have AppleCare. Since the 
connectors we are talking about are not heat sensitive compo- 
nents, there is very little likelihood of making matters worse by 
resoldering and there is a better than a 5096 chance of fixing the 
problem. But, if you are still under warranty or if you have 
AppleCare, you don't have to worry about resoldering - just let 
your friendly dealer replace the power board. 

One suggestion that Don Ritter probably made in jest turns 
outto bea good one. He suggests that you “buy yourself a smoke 
alarm and place itabove your Mac." I'll go him one better. If you 
intend to leave your Mac on unattended, install a stand-alone 
automatic halon fire extinguisher as well as a smoke detector 
above your Mac. 


HyperCard Needs a Diet 
Neil Rieck 
Kitchener, Ontario 

I just sold my 4 year old Mac (it was a 5I2KE with an 
external floppy when we parted company) in order to buy an SE 
with an internal hard disk. I thought that a 20 Meg disk and one 
Meg of RAM would satisfy my computing requirements through 
1990 until I loaded the HyperCard (version 1.0.1) package that 
accompanied the SE. I now believe that HyperCard is a scheme 
by Apple to sell hard disks and memory upgrades (see “What you 
need to use HyperCard" on page xvi of the "HyperCard User's 
Guide"). 

Although HyperCard seems very powerful, I can see no 
reason why the STACKS (HyperCard programs) must be so 
large. A very nasty example is Apple's “1987 HyperCard 
Supplement" which is 773.5K bytes (Data 762.3 K, Resource: 
11.2K). An ASCII dump of the Data Fork revealed that the script 
commands are not stored as tokens (as was done in AppleSoft 
BASIC days when both RAM and Disk space were scarce), but 
are actually in their original text form. Didn't we learn anything 
in the 70's? I found 957 occurrences of “MouseUp” which would 
save 4785 bytes if replaced with 16 bit tokens (or 5742 bytes in 


708 


the case of 8 bit tokens). Can you imagine the savings if ALL the 
script commands were tokenized and SPACES between them 
removed? (Note: The thought of jump tables and command 
tokens reminds me of the trap dispatcher). 

At first glance, you would think that the 221 page “Нурег- 
Card User’s Guide” would tell you everything you needed to 
know about HyperCard. Wrong! If you want to know how to 
SCRIPT (program in HyperCard) or even get a list of the legal 
script commands, you must order the “HyperCard Script Lan- 
guage Guide” from APDA. This would be similar to getting a 
BASIC language package, then finding out that you can only use 
it to run/modify the demos until you purchase further documen- 
tation. At least Apple could have listed the script commands in 
an appendix. 


I am a УАХ programmer by day (I am fluent in several 
languages) and was quite disturbed by comments from col- 
leagues who criticized 4GL type packages like HyperCard. 
Although HyperCard seems to be a hardware hog as I've just 
shown (but it can be fixed), it does allow the average person to 
program the Mac without having to know about GrafPorts & 
GetNextEvent, etc. 

The best analogy I can come up with is the automobile. The 
first cars required the owner to understand the basic theory of 
operation so he could crank start the engine, manually advance 
the spark, set the choke, and shift the gears. Today's cars do all 
these things for you which makes the car available to more 
people. This increases sales, which drops the price for everyone. 
Just imagine, a more powerful Mac at a cheaper price. 

My advice to MacTutor readers is to accept and learn 
HyperTalk (the language of HyperCard) as another language 
because the script market will be huge, and there will be people 
who will find this method of programming difficult and will 
require your advice. А second point to consider is that there will 
be GOOD scripters and BAD scripters, and if MacTutor readers 
setahigh standard now, we сап һауе а positive effect on what we 
will be forced to deal with in the future. And if after all this there 
are some people who are still skeptical of newer and easier to use 
software packages, please remember that in the movie “2010”, 
Doctor Chandra (the system designer) talked to HAL & SAL 
when it was convenient to do so, but also used a keyboard when 
it was required. 

Notes on the Modifier Keys Article 
Warren Michelsen 
Page, AZ 

I just wanted to correct the mis-impression you may have 
created in some people's minds regarding the short LSP unit 
source of mine which you published in the May issue. You may 
recall that it showed how to detect the press of a modifier key in 
LSP and was sent in response to a writer's Question in the March 
issue. 

Most importantly, the functions, as published, do not require 
a posted event, that is, they will detect the press of a modifier key 
entirely independently of “а normal key", contrary to what you 
stated. While I suppose the functions could be used in lieu of 
checking the modifiers flags of an event, that is not what I wrote 
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or use them for. Typical uses are: Upon program start “if 
OptionIsDown then" go directly to a certain function (much the 
way Font/DA Mover "starts up" in DA mode of the option key is 
down at start. Or, “if OptionIsDown” when a user selects “ 
About..." then I bypass the About dialog and go directly to the 
instructions, which are normally selected from a button in my 
About dialog. 

Secondly, while the unit indeed “...does not handle all 
combinations of keys if both the shift and command key are held 
down together..." it is certainly easy enough to call multiple 
functions in succession: "if (OptionIsDown and ShiftIsDown) 
then...” It beats having to remember numerous constants repre- 
senting each possible combination of modifier keys. 

Your readers might appreciate clarification of these points. 
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BNDL Sleuthing 
Georg Newesely 
Berlin, West Germany 

I am a 17-year-old Macintosh admirer from Berlin, West 
Germany. Every day, I spend a lot of time with my Mac SE and 
your fabulous magazine. I have been working with Pascal for 1/ 
2 year now. This year I started with assembly. At this time, I 
come to you with two questions. 

(1) The Video Whiz reported in the Mousehole Report on 
how to use a UniDisk 3.5" for an Apple II on the Mac. Where can 
I get detailed information on how to hook it up (1 don’t have ап 
external drive)? 

(2) Ihave been writing a program called “Icons”. It loads 
up the desktop file, investigates with string manipulations the 
bundle resources to find the ICN# IDs of the applications and of 
the files belonging to them. It scans the BNDL IDs using a loop: 

for index := 1 to CountResources(‘BNDL’) do 


begin 
theHandle := GetIndResource(‘BNDL’, index); 
if theHandle <> NIL then... 

end; 


This is complicated and does not allow the direct access to 
the IDs. Is there a way to get (a) the BNDL IDs directly without 
any scanning, and (b) the ICN# IDs without any string manipu- 
lation? 

At this time, I want to thank you for many happy hours that 
I spent with my Mac & MacTutor™. No опе else brings so many 
aristocratic articles in one convenient package as MacTutor™ 
does. 


Prototyper Review 
David V. Moffat 
Raleigh, NC 

I have to face the music: I wrote the Prototyper review that 
Dan Kampmeier complained about in this column (Letters, 
МасТиюг, July, 1988.) 

Let’s face it: a non-technical magazine like MacWEEK 
needs a non-technical review, one that explores only the surface 
of a complex product. 
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Hype? Is describing the many powerful and easy to use 
facets of a program hype? That attitude flies in the face of what 
we like about the Macintosh. Mr. Kampmeier is being facetious. 

Prototyper is a ground-breaking product, unlike any other. 
If Mr. Kampmeier’s product is similar, but better, he must face 
the fact that it is his responsibility to get that fact across in his 
advertising. On the face of it, his product seems to be just like 
several other pre-written program shells and libraries. 

In my defense — not just to save face — I must explain the 
circumstances behind thatreview. The review (and title) printed 
were not what I submitted to MacWEEK; the editor was faced 
with the problem of making a 1,400-word, 6-picture review into 
a 1,000-word, 1-picture review. He did a pretty good job. 

In addition, Mr. Kampmeier's product had not yet shown its 
face when I wrote the review. 

I also offered to do a technical review of Prototyper for 
MacTutor, but I had no response (sorry, deadlines and space 
considerations are at a premium right now - ed). 

In any case, if anyone took my review at face value and 
bought Prototyper, he got his money's worth. I do not feel that 
I lost face by publishing it. 

Another point: If Dan Kampmeier wanted to say something 
to my face, he should have called me, not MacWEEK. As stated 
in the review, I am in the Department of Computer Science at 
NCSU. 

Iagree that we need some face-to-face comparisons of rapid- 
prototyping and quick-development tools. If Dan would like to 
send me a copy of his interface product (Facelt), I will consider 
writing a review of it. 

But I do not guarantee a happy Kampmeier. 

[I also feel we need a good comparisons of the current tools 
out there for this type of development need. CASE, computer 
aided software engineering, is a blessing as the learning curve 
goes up on new systems.-ed] 
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Font Sorting via the Toolbox 
David Dunham 
Goleta, CA 

In reference to Ray Cameron's Font Dialog Box article: 
Believe it or not, there's a toolbox routine which sorts font names 
(at least with 128K ROMs). Just havea fake (i.e. never displayed 
іп a menu bar) menu, and use AddResMenu (menu, FONT ). 
This does the right thing (or at least the official thing) with 
FONDS and NENTS, and properly ignores fonts starting with “.” 
ог “%” (suchas bold or italic screen bitmaps for PostScript fonts). 
If you want to use this information in a list just call GetItem(), 
CountMItems(menu) times. 


Background Problems 
David Linder 
San Carlos 


First of all, I want to apologize for the “Stone Age” way that 
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I am contacting you. Unfortunately, I have not purchased а 
modem yet for my Mac, so I am unable to reach you via a BBS 
— however, that will soon change... 

Being a recent Mac convert, let me add to the accolades of 
others in congratulating you on a fine magazine. For those of us 
who are caught in the middle of the steep learning curve for Mac 
programming, MacTutoris a much needed resource. Keep up the 
good work — you can count on my subscription for as long as the 
magazine continues! 

As one of my early learn-to-program-the-Mac projects, I 
tried working with Peter Korn's GraphLoad program from the 
March 1988 MacTutor. After typing it in, compiling it, and 
debugging it (using MPW C 2.0), it seems to work just fine when 
the GraphLoad window is the front window. However, when I 
activate a window from another application in Multifinder, 
GraphLoad freezes until I reactivate its window and bring it to the 
front. I thought GraphLoad would run in the background so that 
it would always show system load even when it was not the front 
window. What am I doing wrong? My SIZE -1 resource has the 
following bits set: 

Accept Suspend Events 

Can Background 

Juggler Aware 

Doesn'tthe Can Background bit mean that this program will 
run as a background program? Any help you can give me would 
be appreciated. [Checking the source code as distributed on the 
source code disk #30, the program runs fine in MultiFinder. I'm 
looking at it as I type and it's blinking away. You must have an 
error in your code. Check it against source code disk 30. -Ed] 

Developer Responsibility 
Edward J. Groth 
Scottsdale, AZ 

After seeing the DCM promotional ad on page 23 of the 
June, 1988, MacTutor and being quite disenchanted with the 
horrible implementation of the М5 FORTRAN 2.2 package, I 
ordered and received DCM's MACTRAN PLUS. 

I sent a letter to DCM about a month ago, and since I have 
not heard anything from them, I must assume that they have 
decided to ignore it. The note that came with their package that 
is referred to in my letter reads as follows: 


The file “Пһох Ке!” in the folder “Other files" is cor- 
rupted. You would have to reassemble the program 
“tlbox.asm” with a 68000 assembler. If you do nothave 
one, please send the disk back to us, and we will include 
an uncorrupted, working copy. 


I have sent you this letter for perhaps one or both of two 
reasons. I would like to see MacTutor supply useful and 
complete reviews of such things as languages. The usual maga- 
zines do not review languages but only applications. The user 
base needs such help. Hopefully reviews would include real 
comparisons of strengths and weaknesses of competing develop- 
ment systems. 

The other reason is much more abstract. We really need to 
bring about some degree of maturity and responsibility within the 
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software industry. This business of selling a blister-packed and 
copy protected piece of software without any responsibility to 
make sure that it works, at least somewhat, has got to go. There 
is also no recourse against extravagant and fraudulent claims 
made by many software developers and venders. I really have no 
good way to suggest for bringing this under control, but I am sure 
that exposure to the light of examination and comparison will 
certainly help. It seems to me that MacTutor is in the unique 
position of being able to supply such comparisons. I fully realize 
that this might not be viewed as the most astute business move, 
but I believe that being a real source of reliable information could 
only result in a more loyal readership. 

Thanks for bearing with my frustration. If I can be of any 
help or provide any further information, please let me know. 

[L, too, see no alternative suggestion except maybe the free 
market system. The amount of differing development systems 
and tools is just amazing, not to even mention the constant flood 
of upgrades. I personally do not trust a product until it has got a 
version 2 next to it. We will try, as space permits, to review 
development systems, but frankly, we do not get very many good 
reviews across our desks. -Ed.] 


Disappearing File Icons and Other Problems 
Steve Seaquist 
Temple Hills, MD 
When you drag a disk's icon into the trash can or select Erase 
Disk on it, Finder 5.3/System 3.2 and Finder 6.0/MultiFinder/ 
System 4.2 sometimes forget how to redraw file icons on cur- 
rently mounted HFS volumes. Here's what I’ve found out so far: 

(1) Finder 5.3 doesn't redraw file icons at all and starts 
thinking that disks are too full to record folder changes. 

(2) Finder 6.0 and MultiFinder temporarily draw generic file 
icons, then suddenly gray the desktop, pause briefly and 
redraw the correct icons. (Presumably they read the desk- 
top file during the pause.) 

(3) It's a consistent property of the ejected (or erased) disk. 

(4) Every disk newly formatted by my 5.3, 6.0 or MultiFin- 
der (800K or 400K) starts out with this property: 

(a) Erasing a normal disk causes that disk to exhibit the 
problem when its icon is dragged to the trash in the future. 

(b) Erasing adisk that already has the problem causes the 
icons to disappear as part of the erase process, and doesn't 
fix the disk. 

(5) A visible characteristic of such disks is the fact that the 
Finder doesn't recognize the space taken up by the direc- 
tory and desktop. (It says empty ones have “ОК in disk") 

(6) It'll happen every time with the same disk until some- 
thing fixes it. 

(7) Once fixed, it'll never happen again unless you erase it. 

Out of paranoia, I shutdown or restart when this happens. I 

haven't lost any data yet, but it's very annoying. I don't know 

how other versions of the Finder/System behave in this regard. 
Fixing a disk with the disappearing file icons 

In the process of testing whether Finder 5.5/System 4.1 had 

the same problem, I discovered that simply inserting the disk 

under 5.5 was sufficient to repair it and keep it from screwing up 
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5.3, 6.0 or MF. Although 6.0 and MF recover from the problem 
more gracefully than 5.3, they don't fix the disk the way 5.5 does. 
It would appear that someone removed the 5.5 fix in the devel- 
opment of 6.0 and MultiFinder. 

ImageWriter drafts of LaserWriter'd docs 

This is a user question, but it has developer implications: 

I often have to produce business reports to my clients 
describing what changes I made (or recommend making) to their 
computer systems. I use just about every snazzy Word 3.01 
feature, including footnoting, formulas, intermixed graphics 
(snazzy for those not used to Macintosh), outlining, side-by-side 
paragraphs, style sheets, table of contents generation, etc. My 
clients want to see professionalism in both the interim and final 
deliverables of the report. Because I don't own a LaserWriter, I 
have to go to Kinko's and run off copies there. That's where the 
problems start. 

When Word detects that the Chooser'd printer is a Laser- 
Writer, it changes the font widths. (I use Times-12, mostly.) 
Because word wrap and tabs are affected by the width of text that 
precedes the right margin or tab stop, all the line breaks and tables 
get screwed up. As a shortcut to reformatting the entire docu- 
ment, I change the margins from 1.25" (TW) to 0.98" (LW). This 
keeps the word wrap about the same, but I still have to reformat 
alot of tab settings. To save time and money that would be wasted 
doing this at Kinko’s, I keep a LW driver in my System folder, 
Chooser it even though I don’t have one to print to, and reformat 
it on my system. Then I go to Kinko’s and run off а copy. 

Now what do I do? Do leave the document formatted for 
the LW, so I don’t have to reformat it again the next time I take 
it to Kinko’s? If I do, I won't be able to get a draft copy on my 
IW. Ро І Chooser the IW and reformat it again, so that I can get 
drafts on my system? If I do, I have to reformat it again for the 
next deliverable. It’s absolutely infuriating. My dilemma gives 
rise to several questions: 

(1) Why should the Chooser’d printer affect font width in 
Word? It doesn’t in MacWrite. Word has to be doing it on 
purpose. But why? This is a question of concern to all developers 
of applications that print, including myself. Despite what it says 
at the beginning of Tech Note 72 about printing to LWs the same 
as IWs, we all know there are some reasons to print differently 
(notably page size). But is there a good reason to change font 
widths for LWs? 

(2) More to the point, how does Word change the font width 
according to the Chooser’d printer? I didn’t see any FONT or 
FOND resources in Word’s resource fork, so it doesn’t seem to 
be playing any “APPL file overrides System file” tricks. The 
only thing I can figure is that it could install its own QD 
bottlenecks (like the November 86 MacTutor article on using 
StdText and StdTxMeas to support tabs in text edit), and that the 
LW driver’s QD-to-PostScript bottlenecks end up using Word’s 
bottlenecks that way. 

(3) Does anyone know a way to get Word to image the page 
the same way for both [Ws and LWs? I'll take anything: a secret 
flag editable with ResEdit, an FEdit patch, a disabling of the trick 
in question 2, anything. The direction of the change depends on 
the answer to question 1. That is, if there’s a valid reason to make 
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text take up more space on the LW, then I'd greatly appreciate a 
way to make it take up more space on the IW as well. If not, I'd 
greatly appreciate a way to make its LW output as condensed as 
its IW output. /I suggest you make the following assumption: MS 
Word 3.01 does not work on anything except a Laserwriter 
printer. -Ed.] 

ResEdit 1.0.1 bugs under MultiFinder 

Deleting a string from a STR! resource causes ResEdit to 
crash. My workaround for this problem is to run ResEdit under 
Finder 5.3/System 3.2 whenever I want to delete a string from a 
STR. 

Sometimes ResEdit doesn't see all resource types (or all 
resources within a type) in the system file. My workaround for 
this problem is to restart the Mac and to rerun ResEdit right after 
the restart. 


Volume 4 Number 12 


Prototyper™ vs Facelt™ vs Programmer's 
Extender™ 
George R. Cossey 
Author of Prototyper™ 

First let me say that the goal of Prototyper™ is similar to the 
other two products, but the implementation is very different. The 
goal for all of us is to make designing and building a Macintosh 
program less painful. 

Prototyper™ has a built-in visual editor and simulator for 
interactive graphical design of the user interface, while the other 
two products provide no direct visual interaction in the program 
design. 

Prototyper™ generates source code that uses only Mac 
Toolbox and does not supply any private or additional libraries 
for linking to. The other two products supply libraries to link to 
and provide their own toolboxes to interface to the Mac interface. 

Programmer's Extender™ and Facelt™ both try to make the 
Mac interface less of a challenge by using custom designed 
libraries that combine the functionality of multiple toolbox calls 
along with some canned control code. My objection to that 
method, as a programmer, is that canned libraries work for only 
specific conditions and if my program requires something a little 
extra that is not in the canned library then I have to replace it with 
my own code that uses the Mac Toolbox anyway. Prototyper™ 
generates source code that uses only the Mac Toolbox, so any 
"tweaking" that I have to do to a routine is easily added. 

Icommend both Programmer's Extender?" and Facelt™ for 
developing theirown interface libraries to make programming on 
the Mac easier. Programmer's Extender™ is a fine product that 
shows the dedication and high level of expertise of the designers. 
Facelt™ is a fairly recent newcomer and has potential to provide 
the same level of functionality that Programmer's Extender™ 
does. 

In summary, I developed Prototyper with two main goals in 
mind. The first was to make designing a program's interface like 
painting a picture in MacDraw, with objects that could be resized 
and repositioned visually. The second was to provide source 
code that used only the standard Mac Toolbox and not any special 
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libraries. Both objectives were realized with Prototyper™ , and 
I feel it is in a different class than Programmer's Extender™ and 
Facelt™ which use special libraries of functions. 

[I commend Mr. Cossey on his excellent product. I like 
designing my interface at a MacDraw-type level. Prototyper is 
definitely not perfect. There are many things I would like added 
or changed. But this shows how much I like what Prototyper tries 
to do. I want to improve what it does, not just throw it out. I can 
see in the future that this will be the avenue of interface develop- 
ing. The interactive feel of seeing your interface is very gratify- 
ing. Mr. Cossey, please keep improving Prototyper. I feel you 
have a product with lots of potential. -Kirk Chase, Assistant 
Editor, MacTutor] 

Word 3.01 Word Wrap 
Steve Seaquist 
Temple Hills, MD 

After much more sleuthing, I' ve determined that font widths 
on the screen do not vary according to what printer is Chooser' d. 
The reason why word wrap and tab stops vary between 
ImageWriters and LaserWriters is Word's variation of how it 
measures an inch: 

• Chooser an Image Writer, then Show Ruler, then get 

outareal-world ruler (a tape measure, for example) and 

holditup to the screen. The inches that Word shows are 
notably longer than real-world inches. 

* Now starta print job using Tall Adjusted. Afterwards, 

the word wrap point will change. Then do a Page 

Preview. Afterwards the on-screen ruler's measure- 

ments will also change, and the new ruler's inches will 

be a lot closer to (a tiny bit shorter than) real-world 

inches. (The requirement of doing Page Preview to 

change the ruler is probably a bug. It should change 
automatically to reflect current word wrap and tab 

StODS.) 

• I believe Word is using THPrint()^^.prInfo.1HRes to 

determine the number of pixels per inch in the on-screen 

ruler will accurately reflect the number of inches when 

the document is printed. This is the old aspect ratio 

problem. 

• Dots on the screen are square 74dpi x 74dpi. 

* Dots on IW, Tall are rectangles 72dpi x 80dpi. 

• Dots on IW, tall adj. are square 72dpi x 72dpi. 
To answer my previous questions: 

(1) There is indeed a good reason to change word wrap and 
tab stops when changing between IWs and LWs. The difference 
in aspect ratio would yield a different number of characters that 
could fit comfortably on a line. Because only the center or end 
point(s) positions of lines are guaranteed, the LW driver's QD- 
to-PS bottlenecks would generate lines longer than anticipated 
(left, right, or centered justified) or too compressed (fully justi- 
fied). So the passage at the beginning of Tech Note 72 (about 
printing to LWs the same way as you would to IWs) is mislead- 
ing. 

(2) Contrary to my earlier suspicions, Word wasn't playing 
any tricks to change screen font widths. In actuality, printer 
resolution changes printout font widths, and Word simply adjusts 
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its screen display accordingly. 

(3) The trick to getting IW rough drafts of Word documents 
that are intended to be LW’d is to use Tall Adjusted. I haven't 
seen any mismatches yet, and I don't anticipate seeing any, 
because Word seems to use the same 72 dpi ruler in either case. 
Too bad Microsoft's hotline people didn't know this. It would've 
save some people a lot of sleuthing. 

I'm tempted to use Tall Adjusted and LW fonts in all Word 
documents, so that the decision of whether to LW the doc can be 
postponed. Unfortunately, Tall Adjusted seems to slightly 
improve, but not eliminate, the problem where Best mode print- 
ing jams together words that are in LW fonts. This makes Best 
mode Worst and eliminates the qualitative middle ground be- 
tween Faster and LW (a middle ground that still exists if the doc 
is in an IW font). My only guess as to what causes that problem 
is the facts that FScaleDisable implies FractEnable (Tech Note 
92, page 2) and Best mode printing is scaled down from the 
double-size font if available. 

More DB and C 
Michael D. Sammer 
Bartlesville, OK 

Please letme compliment you on the fine journal, MacTutor. 
I enjoy reading it thoroughly, and it is very helpful. I program 
strictly in C, therefore, I would appreciate it if we could see more 
articles on C. This would be extremely helpful to me. Specifi- 
cally, some articles on database management, hashing tables, 
and details regarding definitions of records ina file would be very 
helpful. Techniques for manipulating data back and forth from 
the disk to a data structure, efficient ways to mark the end of a 
record in a database would be helpful. I am also interested in a 
scheme for searching the database in regard to a group of 
different index parameters, ie, a list of all programmer's who use 
a Macintosh, the C language, and are between the ages of 30 and 
40. Efficient code for this type of a problem would be extremely 
educational. 

Thank you very much for your assistance. Please continue 
the fine work which you and your staff have delivered. 

[The content of MacTutor is determined primarily by what 
people contribute and lately the c people have not been contrib- 
uting much. To get more c into MacTutor, we need more c 
contributions. -Ed] 

MyTENew Suggestion 
Moshe Foger 
Tel Aviv, Israel 

Iwouldliketo commentaboutcalling ROM directly through 
pointers published in the last September issue (Mousehole 
Report, p. 18). In my opinion the code would not work for the 
following reason: 

WhenLightspeed calls the MyTENew, it adheres directly to 
Pascal stack conventions (leaving room for TEHandle and push- 
ing pointers to the two rectangles) and jumps to MyTENew 
leaving the return address on the stack. However in MyTENew, 
the compiler automatically inserts "Link Аб, #0” which creates 
a new activation stack needed to access the function's parame- 
ters. The link instruction saves the previous contents of A6 on the 
stack. The JSR instruction also leaves a return address on the 
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stack; thus when the ROM is activated, it treats the saved A6 and 
the original return address as the required rectangle pointers and 
puts the handle in the pointer to ViewRect... 

To correct it, I would suggest the following in MyTENew: 


TEHandle MyTENewCDest, View) 
dn XDest, *View; 


asn( 
UNLK A6 ¿Balance for Link from compilr 
MOVE (А72%,АЗ ;POP return addr. to safe reg. 
JSR TENew ¿Jump to ROM 
JUMP (A3) ; Return 
) 

) 


Animated Cursors 
David Stoops 
Philadelphia, PA 

I am an engineering undergraduate at Drexel University, a 
school considerably devoted to Apple's University Consortium. 
I am writing in response to the heated discussion of animated 
cursors in the March and May '88 issues. In a rare moment of 
inspiration, I realized that animating the watch is a chore ideally 
suited for implementation as а УВІ Task. Referring back to the 
June '86 MacTutor, which contains an article on screen switch- 
ing animation using the Vertical Retrace Manager, I wrote the 
enclosed snipets of Lightspeed Pascal code that seems to do the 
job. 

The routines make use of the “асш” resource, which should 
be copied along with the necessary ‘CURS’ resources from the 
Finder into the project resource file. To use these routines, first 
call InitWatch to get handles to the cursors, then call StartWatch 
to display the animated watch while your program goes on about 
its business. A finalcallto StopWatch removes the task from the 
vertical retrace queue to halt animation. I find this scheme does 
a better job of animating the watch than that emploed by the 
Finder (notice how poorly the watch hands move during lengthy 
I/O operations under the Finder). Hope this proves useful. 


unit WatchGlobals 
interface 


type 
ecur = record 
whichWatch : 
Watch : 
end; 
acurPtr = ^acur; 
acurHandle = ^acurPtr; 
var 
currentWetch : integer; 
WatchList : acurHandle; 
VBL : VBLTask; 
implementation 
end. 


longint; 
эггау[1..8] of CursHandle; 


unit WatchUtlities; 
interface 
uses 

WatchGlobals; 


procedure InitWatch; 
procedure StartWatch; 
procedure StopWatch; 
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implementation 


procedure InitWatch; (Get the watch CursHendles) 
var 


watchcount : integer; 
begin 
WatchList := acurHandle(GetResource( “асиг”,0)); 


(Will crash if 'ecur^ isn’t available’) 
with WatchList** do 

begin 

for watchcount := 1 to 8 do 
а Tong int CWatchiwateheount 1927; 

whichWatch := 0; 

end; 

end; 


procedure AnimateWatch; (Our VBL routine} 
begin 
SetUpA5; 
with WetchList^^ do 
begin 
if whichWatch >= 8 then 
whichWatch := 1 


else 
whichWatch := whichWatch + 1; 
SetCursor(Watch[whichWatch] ^); 
end; 
VBL.vblCount :=16; 
RestoreA5; 
end; 


procedure StartWatch; 

(Install our task in the vertical retrace queue) 
var 

err : OSErr; 


begin 
with VBL do 
begin 
(Туре :- Integer(vType); 
vblAddr :- @AnimateWatch; 
vblCount := 10; (Update watch every 10 ticks) 


vblPhase := 0; 
err := VInstallC6VBL); 
end; 
end; 


procedure StopWatch; 
(remove our tesk from the vertical retrace queue) 
var 

err : OSErr; 


err :- VRemoveC@VBL ); 


Carl Nelson & Associates Get a New Name 

Our good friend, Carl Nelson, has changed the name of his 
company to Software Architects, Inc. Carl is head of the MacApp 
Developer's Association and is currently working on a number of 
important MacApp projects, including an article for MacTutor! 
Software Architects can be reached at (206) 252-6897 or by 
AppleLink D1846. They are located in Everett, WA. 
A happy birthday to MacTutor, which officially completes four 
years of continuous publication with this issue. The first issue 
was published in December 1984, after MacWorld published 
their September cover story on how to clean your mouse! And 
the rest was history as they say. Thank you to all the faithful 
who have kept the programming dream alive, despite ad 5 
best efforts to frustrate us! 
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Mousehole Report 
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What: suitcase and MF 

From: Venus (Jet Propulsion Laboratory) 

This works just fine, but if (heaven forbid) you read your 
manual, in the current version of Suitcase, Open and Close DA/ 
Font files are disabled. If I am doing something special that 
requires alternative DA/Font/Fkey/snd files, I boot with Com- 
mand key down into Finder, reset the open ...Files, and then 
Option-Cmd-dbIClk the MultiFinder Icon. It'sa bit of a pain, but 
it works fine. I recommend stuffing as many resources into one 
file as possible and just working with it... I’ve got 36 DAs, 8 
FKeys, 125 Fonts, and 15 Snds in one suitcase file named DAs 
and it works like a champ, using only one file buffer for all that. 
Faster booting too. (by some inconsequential fraction of a 
second). [Note: we have found that Edit in the current release 
does not seem to work with more than 24 fonts in the system. -Ed] 

What: Flash command in HC 

From: Greg Kearney (Howard Publications) 

In HyperCard there is an undocumented command called 
FLASH; it is a XCMD that was added to HyperCard after Mr. 
Goodmans book went to press. The form is: 

Flash «а number? 

When called with out a number Flash will make the whole 
card “blink” several times. When FLASH is given anumber, then 
it will blink the screen that number of times. 

What: Control Panel stuff 

From: Jim Reekes (CMS) 

Opening a DA and getting only a beep usually means there 
is not enough memory available for the DA to live in. 

Sam, what does 'rebuilding the Control Panel's desktop' 
mean? 

From: Sam (Apple Computer Inc.) 

The beep heard when opening the Control Panel is telling 
you that it is rebuilding its desktop. The control panel keeps a 
desktop file similar to the Finder's. It knows what icons to 
display and other fun stuff. Unfortunately, when you clear the 
PRam it also rebuilds the Desktop which takes a considerable 
amount of time if you have a large number of CDEVs. 

What: Clearing PRam Sometimes Doesn't! 

From: Larry Nedry (Mousehole Download Sysop) 

As I said in a previous post, I can clear PRam with an older 
.System & Finder but not with the latest. Have you tried it with the 
latest, Sam I have plenty of memory (4 Meg) so that isn't the 
problem. Anybody else had a problem with this ? I know of at 
least 2 others that have this problem also. What gives? 

From: Power Hopeful (Maryland) 

Larry, try giving the Finder more than the 160k that it claims. 
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Rusty Hodge 
Contributing Editor 
Mousehole BBS 


I also was having memory problems, but since I allocated 256k 
to the Finder things work fine. 

I had an interesting and puzzling experience over the week- 
end. On receiving a new external hard drive, I was plagued by 
problems trying to set it up. I kept being told that there was no 
SCSI device connected in the programs I was using for that 
purpose. My elimination of the various things that might be 
causing this - such as changing the cables and even changing to 
a different Mac without an internal HD - had no effect on the 
situation. Since I have another external HD, I could pretty well 
eliminate the HD hardware as the cause since neither (both with 
terminators) showed up. 

I knew it had to be a hardware problem, but I could not 
imagine what. Finally it occurred to me that I was using my new 
extended keyboard (which I don't like). Guess what: THAT was 
the problem! When I switched back to the old keyboard, every- 
thing functioned perfectly. [?? I don’t get this at all. Someone 
please check this out. -Ed] 

What: Radius Accelerator 

From: John S. Lee (Argon Software Technologies) 

Just bought some new toys for the Mac. The Radius Accel- 
erator w/ 68881 co-processor: This seems to work fine with 
MOST software. I have not had achance to run all of my software 
on it, but as expected there are NO problems with TML 2.x (Гат 
using 2.1), and NO problems with LSP 1.11. RR 9.4 will NOT 
Work with the Accelerator (orcould it possibly be the new System 
and Finder). My DataFrane 20 (1 year old ), needed some update 
software which I got today (Manager 3.21) and it works wonder- 
fully with the Accelerator. I also have a Bering 20-20 removable 
and it works fine with the Radius. The drive will not boot up by 
itself, this is primarily due to the ROM versions inside the drive. 
Bering said they will ship them to me as soon as I write for them 
(strange, but true ). Otherwise the drive works well with the 
Radius. Also got the Plus expanded to 2.5 for some leg room. 

If Ifind any discrepancies with software and the Accelerator 
I will post it here. But so far it seems as though it is quite a solid 
piece of hardware. 

What: Find File suggestion 

From: Jim Reekes (CMS) 

Use ‘Find File’ to locate the desired file. Type Cmd-M or 
choose ‘Move To the Desktop’ from the menu. Double-Click the 
icon to open it. 

When your done with this file, at the desktop select the icon 
and choose ‘Put Away’ in the Finder’s ‘File’ menu. Find File will 
also set the ‘Standard File’ dialog to the directory that the file is 
located in. This means that if you had used Find File in an 
application and located the file your looking for, then used the 
‘Open’ file command from your application it would be inside 
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the folder that you had just found your file in. Make sense? Well, 
why ya think they called it *Find File'? 

I would like to see this option inside of the 'SFGetFile 
dialog. That would be a cool new feature. Think Technologies 
has an INIT file that does this. 
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From: jimr (Jim Reekes) 

Subject: add 

The bogus FONT problem I've been complaining about 
with PageMucker also occurs in Illustrator. It is exactly the same 
problem where all the fonts, menus, and dialogs are totally 
unreadable. 

I also had a similar problem today using MS Word 3.01 and 
the Background Print application in MultiFinder. I had a page of 
Palatino text, which I printed with “Fractional Widths” selected 
in the Print Dialog. As it began to print, the lower left corner of 
Word's window became garbage. This went away as soon as the 
print job was completed. 

But the other strange thing is whenI switch over to the Print 
Monitor to view the job in progress. It had the same problem that 
PageMucker and the rest have with FONTS, menus, and the 
dialog. Its all full of garbage. 

From: jimr (Лт Reekes) 

Subject: Re: FONT problem solved! 

Okay, so I spent nearly an hour trying to locate the source of 
my problems with PageMaker, Illustrator, Word, Print Monitor, 
etc... 

What I did was start with a fresh new copy of the system/ 
finder. Then added my Laser fonts (which have been renamed to 
* Times, Helvetica, etc.). That still worked fine. Then I added 
the fancy ImageWriter fonts that I’ve used for the past few years. 
They are Dali, Boston, Alexis, Dover, Florence, and probably 
another one or two. That's when I started getting into trouble 
with the above programs. Then I removed all of the fancy 
ImageWriter fonts, but I still had troubles. 

So, started back with a fresh new system/finder. Addedonly 
my renamed Laser fonts and settled with that. Never use the 
ImageWriter lately anyhow. My conclusion is that the Font/DA 
Mover is scrambling the FONT resources. This is what got the 
above mentioned applications into trouble. Even after removing 
the offending fonts, the applications would remain screwed. So 
now I'm happy and using PageMAKER once again. 

[In the November issue, we published a solution to font 
problems with Pagemaker. Check the FOND resource flag word 
with ResEdit and make sure it is set to $6000 for older 
Imagewriter fonts. Pagemaker is trying to read a non-existent 
width table in the FOND resource for these Imagewriter fonts 
and that is why the fonts are messed up. We’ ve done this and have 
had nofurther problems with fonts in our systemfile. Pagemaker 
and Illustrator are the only two I know that use the FOND 
resources for calculating character widths. -Ed] 

From: dirck (Dirck Blaskey) 

Subject: Font bugs 

А font bug: Starting with system 4.1 and continuing on into 
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4.2, the following occurred: An application has a font in it's 
resource fork (e.g. Times 9). If said font is not in the system file, 
a setfont will get a SCALED version of the font (e.g. Times 10) 
from the SYSTEM file. If the font IS in the system file, a setfont 
will get the font from the APPLICATION file. /We recommend 
removing all fonts from application files. -Ed] 

From: davidw (David Whiteman) 

Subject: Mac Il problem with ADB 

Has anyone heard of problems with the Apple Desktop Bus 
circuitry with the Macintosh II? Three Mac II'sownedb by friends 
of mine had to have motherboards replaced because the Mac 
would not respond to either keyboard or mouse input. This 
occurred after they switched from the standard keyboard to the 
extended keyboard, and subsequent attempts at trying different 
cables, keyboards or mice did not fix the problem. Has anyone 
else been having this type of trouble? [Т have the extended 
keyboard and the Mac II and no problem like this. -Ed] 

From: powerhopeful (Power Hopeful) 

Subject: Re: Mac Il problem with ADB 

Yes, I’ve had problems like that. Mine seem too to interact 
with SCSI. Anytime I add anything new or change the order of 
SCSI devices, it takes me about a day to get things to function 
correctly. 

From: rick (Rick Boarman) 

Subject: Re: Mac Il problem with ADB 

I had to replace the mother board on my MacII for those 
exact reasons. I think what killed it is that I pulled the keyboard 
cable out with the power still on (I know, it was stupid to do that). 

From: s.winders (Scott Winders) 

Subject: PRam and System 4.2 

Clearing PRam with System 4.2 is slightly different. The 
"Shift-Option-Command key down while opening the Control 
Panel” function remains the same. The difference is this: Only 
the PRam locations that can cause problems with the system are 
reset. These include: Startup Device, serial port settings, sound 
settings, and a few more. Things like the time, date, keyboard, 
mouse, and sound volume settings are not affected. This undocu- 
mented change has led to the confusion about this function not 
working. 

From: jimr (Jim Reekes) 

Subject: PRam and System 4.2 

I just got hold of David Ramsey's new INIT file for Mac II 
users. It will protect us against the evil PRAM woes. I'm not 
exactly sure what it does yet, but David has expressed to me that 
he knows what is wrong with the PRAM and has solved it. This 
INIT will become part of the next system release, sometime in the 
first quarter of '88. I think I already saw this file on the download, 
I'll have to double check. 

From: don (Don Melton) 

Subject: PrintMonitor bug & MacDraw 

Idiscovereda peculiar bug with MultiFinder's PrintMonitor 
а few weeks ago. It seems the good folks at Apple didn't set the 
default memory size large enough on PrintMonitor to make it 
compatible with their own MacDraw. 

Here's the fix: 

From the Finder, click on the PrintMonitor and choose Get 
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Info from the file menu. Change the preferred memory size from 
78K to 80K. Close the Get Info window. 

That's it. Two stinking kilobytes of RAM! That drove me 
nuts for an afternoon. Has anyone else had this problem? 

From: davidk (David Kosiur) 

Subject: PrintMonitor Size 

Where did you get your copy of PrintMonitor from? Mine 
came with Apple's System Upgrade 5.0 and the size resource was 
already set to 80K. Someone may have played with yours before 
you got it. 

From: don (Don Melton) 

Subject: Re: PrintMonitor Size 

I got my PrintMonitor from Developer Services like all the 
other certifieds around here ... and mine was set at 78K. Appar- 
ently they know I'm funny looking or something. 

From: billr (Bill Rausch) 

Subject: finder open command 

One simple way to solve some of the folder confusion when 
using Multi-finder and Finder and other programs would be to 
have Apple modify the Finder Open command slightly. If no file 
is selected when Open is picked from the File menu, have Finder 
bring up the standard file dialog box with only applications listed. 
This way you could launch programs from MF without having to 
reorganize your desktop all the time. It would be useful from the 
regular Finder also although the Option-Open of the folders does 
the trick there. 

From: geoffbryan (Geoff Bryan) 

Subject: FKEY characteristics 

Here is a question for the gurus (Isr?) — when an FKEY is 
invoked and its code is loaded, is that code locked? Assuming it 
isn't, isn't it risky to call anything that might move unlocked 
blocks around while the FKEY code is executing? Any opinions 
out there 

From: Isr (Larry Rosenstein) 

Subject: Re: FKEY characteristics 

The system does lock FKEYs before calling them. 

| It should be OK for the FKEY to move memory. First, the 
very act of reading in the FKEY requires allocating memory. 
Second, FKEYs are run when the application calls GetNextE- 
vent. GetNextEvent is listed among the routines that can move 
or purge memory. By extension, FKEYs are allowed to do heap 
allocations. 

From: dmark (Dave Mark) 

Subject: Restoring Device CLUTS... 

This is atoughy (Ithink)! OK, first things first - I'm writing 
an application that directly accesses the video memory (instead 
of writing directly to a window). Ithen use SetEntries to load my 
own Colors into the current device's Color Table. My problem 
comes in restoring the original Color Table when my program is 
done. The likely candidates seem to be SaveEntries and 

RestoreEntries. Has anyone used these successfully? No matter 
what I try, my program crashes. Another method I tried was to 
save off the CSpecArray, and then restore it myself when I'm 
done. Unfortunately, whenIlook at the Color Table accessed via 
GetGDevice^^.gdPMap^^.pmTable^^.ctTable, there doesn't 
seem to be any valid RGBs (justa few -1s, followed by a whole 
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bunch of Os). Does this mean that a default of some kind is being 
used? I’m trying desparately to get something running in time for 
the MacExpo! Any and all help is greatly appreciated. I have the 
latest and greatest Volume V from АРБА. You сап reach me at 
NASA headquarter’s during the day at (202) 453-8737. My 
name is Dave Mark. 

From: Isr (Larry Rosenstein) 

Subject: Re: Color Pix 

I think CopyPix is superceeded by CopyBits, which can 
distinguish Bitmaps and PixMaps and does the right thing in 
either case. CopyPixMap has an entirely different function, I 
believe. I think this call just duplicates the PixMap structure, but 
doesn't copy the actual bits. (I don’t have my Inside Mac volume 


5 around, so I am going from memory.) 


From: the cloud (Ken McLeod) 
Subject: CopyPix/CopyBits 

That's what I think, too. I was under the impression that 
ІМУ5 was in a state of flux still, so I asked. CopyBits will do all 
the tricks I need it to, anyway... 

From: dhill (David Hill) 

Subject: resource fork size? 

Iam writing a program that has data files that store informa- 
tion in the resource fork and I need to be able to calculate the size 
of the resource fork so that I can display the file size from within 
the program. Does anyone know which call I use etc? Thanks- 
— Dave Hill (formerly the Corsair) 

From: rsiegel (Richard Siegel) 

Subject: Re: resource fork size? 

You don't want to write data directly into the resource fork 
without going through the Resource Manager. 

In any case, you do the following: 

err = OpenRF(neme, vRefNum, &path); 

err = GetEOF(path, &count); 

err = FSClose(path); 

Now, “count” (along) will contain the number of bytes in the 
resource fork. —Rich Siegel, THINK Technologies. 

From: the cloud (Ken McLeod) 

Subject: Tear-Off Menus In LS | 

The tear-off menu code in December’s MacTutor seems to 
have problems with the Lightspeed Pascal environment. (LS 
Pascal v1.11, System 4.2/6.0) The problem occurs when the tear- 
off window is initialized in the “таш” part of the program: the 
windowDefProc field of the window (which is not visible at this 
point) is set to a pointer to the new window definition function. 
If this code is commented out, all works well within the LS 
environment (of course, the tear-off window will be a ‘normal’ 
documentProc type); otherwise, something gets confused badly. 
The patterns become garbage, and you can't quit (in fact, you're 
lucky to escape into Macsbug). Oddly enough, the code in the 
“МакеМепиѕ” proc sets a pointer to the new menu definition 
routine in exactly the same way, and this works without a hitch. 
Also, if the code isn't run under the LS environment but merely 
compiled directly to application form, everything works as it 
should. I should also mention that I removed all toolbox initiali- 
zation calls from the code (InitWindows, InitMenus, etc.), letting 
LS handle it. Can anyone (Rich?) shed some light on the 


717 


interaction of LS with new window definition routines (pertain- 
ing to Darryl's technique?) 

From: Isr (Larry Rosenstein) 

Subject: Re: Tear-Off Menus іп LS 

The technique used to install the defprocs (both the window 
and menu defprocs) trashes the heap. The code is directly 
modifying the master pointer. Memory blocks have back links 
which are used if the block needs to be relocated. It is possible 
that when you compile the program as an application it happens 
to work because the heap is never compacted; when running 
under LSP, you probably aren’t so lucky. 

The correct thing to do is allocate a 6 byte handle and place 
а JMP instruction in that handle. Then store the handle into the 
defproc field. 

P.S. Although the article showed how to tear off a menu, it 
did not show the really tricky part: how do you make sure that the 
torn off menu always appear on top of all your windows? I would 
like to see a follow-up article to address this. 

From: robh (Rob Humble) 

Subject: Print Report Bug 

Am I alone with this bug? I have two different stacks, each 
set up as a simple database, each with about 400 cards. When I 
attempt to do a Print Report, I often get blank pages in the report. 
Page 1 may have cards 1-25, page 2 will have 26-50, page 3 will 
be blank, and 4 will have cards 76-100. If I add or delete а card, 
the problem may go away, or may just shift to another page. An 
attempt to reprint the report without changing anything will skip 
the same page or pages. Also, the page skipped is not the same 
when the print is done on the IW or Laser. 

I have talked to Apple directly, and sent them a copy of the 
stack. They confirmed the problem, forewarded it to Cupertino, 
and now I can't even get them to return my calls. 

From: davidk (David Koslur) 

Subject: Mac-VAX SQL 

Okay guys, run down to DEXPO and see Bob Denny 
demonstrate his latest feat of legerdemaine, SequeLink. Se- 
queLink allows you to use 4D or HyperCard as a smart front-end 
to an SQL database on a VAX. It'll blow your mind! Makes 
“seamless integration" something that's here now! 

Slowing down a bit — initially SequeLink supports 4D and 
HyperCard on the Mac, and Oracle on the VAX. A library for 
accessing the SequeLink driver on the Mac is partof the package, 
SO you can write your own applications. Other SQL dbs will also 
be supported later. $395 for the Mac (including 4D runtime) and 
$1500-$10,000 for the VAX. 

Onelast thing. SequeLink lets you run multiple processes to 
one or more SQL databases without a sweat. It's also MultiFin- 
der-compatible. 


Volume 4 Number 3 


From: billr (Bill Rausch) 

Subject: MacTutor article Bug 

I just had a two page tech note printed in the January issue 
of MacTutor. It has an error. The address of the EventRecord 
must also be passed to the routines doing the event processing for 
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the various window types. Sorry. Bill 

From: jimr (Jim Reekes) 

Subject: Finder problems 

Is there a problem with the Finder or MultiFinder copying 
large amounts of files? Reason I ask, I couldn't copy ту “Utils” 
folder that contained about 300 files (or 7.5MB) while running 
MultiFinder on a 4MB Mac II. It gives a message "Ran out of 
memory..." I tried to reboot into the Finder, but the same folder 
caused a ВОМВ--01 error with the said folder. Had to copy it in 
smaller chunks. 

From: jck (Jack Kobzeff) 

Subject: copying files in MF 

Itdoes seem that running with MultiFinder sure can limit the 
number of files you can copy. Even if there is no other program 
loaded, it looks like it can only use the memory allocated for 
Pinder. I’ve run into this even with a fairly small number of files, 
you still get the “ош of memory' message. Whereas when 
running without MF, it copies several times the number of files 
without a problem. 

From: rick (Rick Boarman) 

Subject: Re: Finder problems 

I had many problems using MultiFinder and large folders 
until I allocated 512k for it to use. After that, no more problems. 

From: rusty (System Administrator) 

Subject: Re: Finder problems 

I’ve had a few “тап out of memory’ dialogs when trying to 
copy one hard disk to another under MultiFinder. Re-starting 
without MultiFinder made it work fine. 

From: Isr (Larry Rosenstein) 

Subject: Re: copying files in MF 

There was a discussion of this on Usenet. The Finder uses 
the MF temp memory services for copying the files, but it has to 
use the Resource Manager to update the desktop file. This is the 
place where the Finder can run out of memory. 

The Finder also uses a fixed size (200K, I recall) buffer for 
the copying, unless the copy involves removable media. Then it 
uses as much memory as it can grab to minimize disk swapping. 
However, there is a limit of about 40 file forks that it can copy in 
one pass, so if you copy a lot of files (or a lot of files with both 
a data and resource fork) then there may be extra disk swapping. 

From: mark.chally (Mark Chally) 

Subject: Multifinder file copies 

According to the MultiFinder Programmer’s Guide thing, 
the finder checks to see if MultiFinder global pool type memory 
(I don’t remember the frigging terminology) is free. It then 
allocates as much as needed/or as much as it can. If you don’t 
have any spare memory outside of the finder area, maybe this can 
bea big problem. Some programs can hog that other memory... 
It also said that if you don’t have enough spare outside memory 
to be allocated by Multifinder, the Finder uses a small, spare 
buffer of its own. Don’t know about errors though—I haven’t 
had any problems—but I’m using four megs too... 

From: jimr (Jim Reekes) 

Subject: new desktop management 

There is a ‘Desktop Manager’ that I’ve uploaded to the 
MHDL. It has been taken from the Apple Share system folder. 
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Itisa MUCH faster method of keeping track of the desktop while 
in the Finder/MultiFinder environment. Anyone that is using a 
80MB (or bigger) drive should put this file into their system 
folder and then reboot. After that, you can delete the desktop file. 
It is no longer used by the Finder/MultiFinder. 

The new method of desktop management is to use B trees 
instead of the resource manager. This has already proven itself 
to me as a BIG improvement of the desktop's performance. 
Copying very large directories and lots of files only shows the 
"updating desktop file..." message briefly. Returning to the 
Finder is also quicker. Only drawback is that we can no longer 
unmount volumes by dragging the hard disk to the trash. Small 
price to pay. (Anyone can get this file from the Apple Share disks) 

[Why didn't Apple distribute this file as part of the regular 
system 5.0 update if it is such an obvious improvement? -Ed] 

From: dhill (David Hill) 

Subject: multifinder Window Funnies 

I found something interesting out about MultiFinder the 
other day. It will not put any of your windows in the front until 
your application calls GetNextEvent(). I found this out when I 
was calling SelectWindow() then ShowWindow() for my about 
window while the program was booting up. But when it would 
run under Multifinder, the about window would open behind the 
finder windows. The fix was to make a call to GetNextEvent 
before opening the about window. 

From: jimr (Jim Reekes) 

Subject: Re: multifinder funnies 

Ialso found this out while trying to open a window during the 
boot process. I was using Dialog Manager calls. Until the 
program calls either GetNextEvent or WaitNextEvent, the 
program's layer doesn't come to the front. Ever seen a modal 
dialog in the background? 

From: the cloud (Ken McLeod) 

Subject: 'acur' resource 

Is Apple going to make the workings of the *acur' (animated 
cursor) resource public? I don't see it mentioned in Inside Mac 5, 
but the latest ResEdit has a template for it...hmm... It would be 
greatto beable to use animated cursors in other programs than the 
Finder! So...how ‘bout it? 

From: rdclark (Richard Clark) 

Subject: Animated Cursors 

If you examine the Finder's “асш” resource using ResEdit 
(some recent version), you'll see what the format is. But, to 
summarize: 

«Number of Frames: Int» 

«Frame counter: Int 

[repeat n times:<CURS ID:Int <Filler:Int] 

Namely, a bunch of integers. 

A typical entry would read: 

Number of Frames: 2 (* This is a short one! *) 

Frame counter :0 (* typical *) 


CURS ID : 128 (* First cursor *) 
Filler : 0 

CURS ID : 129 (* Second cursor *) 
Filler : 0 


Writing a program to use this information is left as ап 
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exercise to the reader (although I may decide to do it myself some 
day...) 

From: the cloud (Ken McLeod) 

Subject: Re: Animated Cursors 

Thanks...actually I was hoping Apple had plans to imple- 
ment this as a patch to SetCursor or something (that is, on a lower 
level than my having to write it!) so that if I set the cursor to one 
with ап ID included in an “асш” list, the animation would be 
automatic... 

From: cderossi (Chris Derossi) 

Subject: Re: Animated Cursors 

Animated cursors are meant to perform two functions. First, 
they show the user that some lengthy process is underway, and he 
shouldn't panic. Second, the movement shows that the program 
hasn't crashed. But actually, the watch cursor itself handles the 
first requirement, so the animation is for the second reason. 

This means that if you do the cursor animation as an interrupt 
process (like a VBL task, as some do), your program can crash 
and the cursor will still animate. So in order to use the animating 
cursor to show that the program is still alive, the program itself 
has to make the call to animate it. 

And since that call is just SetCursor, addition System sup- 
port isn't really needed. Granted, the System could help you 
figure out which cursor was next, but that isn't a very hard 
calculation. 

Each of Apple's programs that animate the cursor (i.e. the 
Finder), do the work themselves. The “асш” resource is just a 
handy mechanism for getting all of the data in a reasonable form. 

From: the cloud (Ken McLeod) 

Subject: Re: Animated Cursors 

You're right, of course... I tend to think more thoroughly 
about these things after my initial confused ramblings, but hey, 
I'm ап impulsive poster. I do appreciate the answers and discus- 
sion generated about things that aren't necessarily documented 
elsewhere. It seems to me that the way to implement animated 
cursors must involve some sort of low-level installation, so that 
the repeated calls to SetCursor are asynchronous (something like 
a call to SetSound, for example..strike that..*StartSound*), and 
not just inserting a SetCursor(ID + 1) in every loop (assuming I 
have aloop to work with). Perhaps this will become ridiculously 
clear the moment I log off... 

From: billr (Bill Rausch) 

Subject: Re: Animated Cursors 

Yes that is exactly what you do -> inserta SetCursor(nextID) 
into each and every place in the program where you need it. As 
it turns out, making it into a separate function SETCURSORO 
isn’t very tough. I use C, and just made the whole thing into a 
macro. Like Chris Derossi pointed out, setting it up as something 
automatic doesn’t accomplish anything as far as the user is 
concerned. It is just as bad as using hardware blinking on 
terminals connected to minicomputers or mainframes with a 
message that such and such is happening. I’ve seen people wait 
hours on a dead program in situations like that. 

From: royh (Roy Hashimoto) 

Subject: Dumping PostScript 

Does anyone know how to get the Laserwriter driver to 
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dump PostScript toa file instead of out the AppleTalk line? Is this 
an ‘official’ feature, or just a debugging back door? [It is an 
official feature; just press cmd-K after clicking OK at the print 
dialog. This dumps the postscript and the LaserPrep header to a 
file named 'postscriptO' . Cmd-F dumps without the LaserPrep 
header. Any cmd-K dump can later be sent via a postscript 
dumper utility and will print as expected. You can even edit the 
file as we demonstrated in a previous MacTutor, to get double 
column printing from data base programs that don't know how 
to format in columns easily. -Ed] 

From: mikesteiner (Mike Steiner) 

Subject: FullWrite Pro eats memory 

FWP really requires at least 2 megs (and more if you want to 
use it under MultiFinder). With a 1 meg Mac Plus, and TOPS 
active, there is notenough memory to even open a new document. 
With TOPS off, but with Suitcase active, there isn't enough 
memory to handle all functions. I had a “not enough memory" 
message when I tried to reshape a bezier curve and when I tried 
to resize a graphic. This was with the demo version they gave 
away at Expo. 

From: markg (Mark Guidarelli) 

Subject: Color resource support... 

ОК I have a question...has anyone seen a program that will 
allow the designing of color cursors, icons, pattern or control 
items? Ihavelooked around and none are to be found. One would 
think that Apple would have added that to ResEdit by now, but 
the most recent version of it doesn't support it. So unless one of 
you heroes out there has one or know of where I can get/ 
buy(cheaply) one ГИ have to write one.... It wouldn't be all that 
difficult but I would rather not re-invent the wheel (out of pure 
laziness). /What you describe is not available, but COLORIZER 
from Palomar Software, available from the MacTutor mail order 
store,isa useful color utility that has some of this capability. -Ed] 

From: rguerra (Rich Guerra) 

Subject: List Manager Question 

I've been using LightSpeed Pascal to write an application 
that uses the List Manager. I create a list and draw it in a window. 
All functions (scroll bar tracking, highlighting, hit processing, 
etc.) are functional. A user double clicking on an item in this list 
causes another list to be created and drawn in the same place as 
the first, thus replacing it. Thisis where I run into a problem. This 
second list is functional in all ways save one: the scroll bar does 
not work. One can scroll the list by dragging the mouse, though 
with appropriate scroll bar tracking. Ican even switch back to the 
original list which works perfectly. [know LClick is being called 
for clicks in the scroll bar of the second list. In fact, I create the 
second list exactly the same way as the first. This may be 
something obvious, but I’m at a loss. Any suggestions would be 
greatly appreciated. 

I’ve tried the obvious things first: 

The boundary rectangle for the second (and subsequent) 
list(s) includes the scroll bar (It is the same one that I used in the 
first list which works.) LClick does get called when I click on the 
non-functional scroll bar. 

I turn drawing off оп the first list [ 
LDoDraw(FALSE,FirstList); ] and also deactivate it [ 
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LActivate(FALSE,FirstList); ] before swapping the second list 
into the display rectangle which is then activated and drawing set 
to true. 

The lActive flag of the second (and subsequent) list(s) with 
a non-functional scroll bar is TRUE. The weird thing about this 
is that the scroll bar will track with the list when you drag on the 
items, still won't work when you click on it, though. Also, when 
the first list is swapped back in, the scroll bar works perfectly 
again! [Sounds like you are not getting the proper control handle 
for the second list to your scrolling routine. -Ed] 

From: jaff (Mark Jaffe) 

Subject: Re: Linking Desk Acc with MPW C 

Sonny: Ihad similar problems with a cdev т MPW. What's 
happened is that you have some data that C puts into a DATA 
segment, and it's trying to use a (nonexistent) INITIALIZA- 
TION code. You probably have a STR or some other data. 
Everything used by Stand alone code MUST come from re- 
sources. If you are writing a DA, they must be referenced from 
the DRVR refnum. Suggest you study some other РА code 
examples (try Art Browser DA) Good Luck! 

From: dirck (Dirck Blaskey) 

Subject: LSC libs 

To whom it may concern at Think... (Rich?) the realloc/ 
relalloc functions in storage.c are USELESS! 

From: dirck (Dirck Blaskey) 

Subject: LS C compiler bug 

LightSpeedC generates two (2) ILLEGAL INSTRUC- 
TIONS in the following code fragment: t() ( registerlongd; int 
i; dli 44-і; } 

From: robh (Rob Humble) 

Subject: LSC Printing 

I just go LSC at the show, and for a beginning C hacker, its 
great. But, the first project I have in mind requires access to some 
of the printing toolbox calls, specifically PrValidate, which is 
part of the print record. In looking through the docs I got (v2.15) 
Ican'tfindany support for this. Am I wrong, is there a library that 
provides the support, or am I going to have to find another way 
to do what I want (determine the Chosen printer, a la Tech Note 
72). [Printing support is now in the ROMs, rather than a separate 
linkable print interface. See the Feb. issue of MacTutor for a 
Pascal example of printing a quickdraw picture. -Ed] 

From: the cloud (Ken McLeod) 

Subject: INIT icons Il 

I just heard that the code for placing an INIT's icon on the 
screen in the lower-left corner at startup was placed into the 
public domain by its author, and people have been putting it to 
use, hence the proliferation of INITS that show icons. What is the 
"true story" here? Can anyone direct me to this code, if it exists? 

From: isr (Larry Rosenstein) 

Subject: Re: INIT icons II 

The code to do this is called ShowINIT, and was written by 
Paul Mercer (now of Apple Developer Tech Support). He just 
released a new version at Mac World Expo, which is compatible 
with a future INIT 31 resource that will perform the same 
function. You can contact Paul at: AppleLink: — Mercerl 
Delphi: PAULMERCER CSNET: 
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pmercer@ Арріе. СОМ 
Cupertino, СА 95016 

From: Isr (Larry Rosenstein) 

Subject: Re: Tear-Off Menus іп LS 

Ialready wrote aTMenu object type that implements custom 
menus easily. Instead of worrying about defprocs, you define a 
subclass of TMenu and implement a couple of methods. The 
code for this is available on the 1st MacApp Developer Associa- 
tion disk. It would be easy to so asimilar object type to implement 
custom windows. 

From: thought.police (William Evans) 

Subject: ApplIScratch 

Did I read somewhere that they were taking ApplScratch 
(the 12 bytes of low-address global space which can be used by 
an application for anything it wants) from us, or is that my 
imagination? It's probably my imagination, but if it isn't, don't 
want to get bitten? 

Any help in exorcising my hallucinations would be appreci- 
ated. 

From: dorourke (David O'Rourke) 

Subject: Re: ApplScratch 

I'm not sure but from talking to a friend of mine at Apple 
you're not having delusions of grandure and the low memory 
globals you talk about are there. 

They were originally documented in the 3 ring binder 
version of Inside Macintosh but were dropped in the “published” 
version. So far I haven't noticed any official reason not to use 
them, but you have to admit that's just too good to be true and 
since they aren't in the most recent version of Inside Mac I doubt 
Apple is going to support them in the future. 

In fact I am guessing that Apple doesn't support them now, 
since Multi-Finder does switch (so I'm told) some of the Low 
Memory between applications. You might have a problem if 
you're running next to another application that uses those loca- 
tions. It depends if MF switches and saves those for you, and if 
it does what happens if you try to access them while you're 
application is in the background. All sorts of nasty problems are 
associated with things like this so I wouldn't. 

Now for some legend and some facts. Early versions of 
MicroSoft software reportedly used these locations to indicate if 
there had been a "key" disk inserted at an early time. Microsoft 
did this so that you only had to put the key disk in once, and then 
as long as you didn't turn the computer off it would remember 
that the copy you were running off of was alright. Now we're 
talking early Mac stuff here, when the 128K was the new kid on 
the block. 

Now for the legend: Apple reportedly put those locations 
there at Microsoft's request, and in fact in early 3 ring binder 
versions of inside Mac there are some locations that have refer- 
ences to Microsoft. 

Disclaimer: None of this information is official and I have 
no formal ties with Apple. Information presented here is to relate 
what I know and have heard over the years. I also have no 
association with Microsoft and I do not speak for them, and the 
information regarding them is also undocumented. 

From: cderossi (Chris Derossi) 
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US Mail: P.O. Box 160165 


Subject: Re: AppiScratch 
. AppiScratch is (briefly) documented in Inside Mac, page I- 
85. This reference does not give its location, but it does say that 
ApplScratch will be preserved across ROM calls. 

It also warns that ApplScratch must only be used by appli- 
cations. INITs, cdevs, DRVRs, MDEEs, etc can't use this loca- 
tion. (MultiFinder must switch them across applications.) 

From: |типккі (Juri Мипккі) 

Helsinki University of Technology, Finland 

Regions: The Real Story, a Technical Note 

1. What We Thought We Knew 

The May 1987 "ABC's of C" and October 1987 “С Work- 
shop" in MacTutor provide descriptions of the region data 
structure. Obviously the region structure is reserved by apple and 
subject to change without notice (it's undocumented), but some- 
times it's just too slow to do things the way apple intended us to 
do them. For this reason (and debugging purposes) it is useful 
to be aware of the structure. Unfortunately the *ABC's of С” 
article is not complete and the “С Workshop” gives slightly 
false information. 

2. Conventions 

In this note the structure I call the region is in fact the data that 
comes after the length word and size rectangle. The first 10 bytes 
are documented and are thus of no interest to us. While I’m on the 
subject of documentation, I might mention that the note in IMI- 
183 about the speed of OffSetRgn is misleading. None of the 
information in a region is stored in offset format and OffSetRgn 
is a relatively slow operation when the region is very complex. 

3. What We Now Know 

A region can be thought of as a collection of block descrip- 
tions, but each block is related to those above it. The block 
description starts with the smallest line coordinate included in the 
block and ends with a $7FFF. The words in between the start and 
end describe the difference between the current block and the one 
above it. 

Let's examine a union of two rectangles: 10,10-100,100 and 
80,80-200,200. The first line would then contain 10, 10, 100, 
$7FFF. This means that the first block starts at y position 10 and 
the pixels between x 10 and 100 are included in the block. The 
block extends until the block below it starts. The following block 
describes the changes to be made in the previous block. The 
second block would then be: 80, 100, 200, $7FFF. This means 
that those pixels that were between 100 and 200 should be 
inverted starting from y position 80. 

The next block would then tell us to remove pixels between 
x positions 10 and 80 starting from y position 100. It should look 
like this: 100, 10, 80, $7FFF. The last block of our region would 
then cancel the remaining pixels from the block: 200, 80, 200, 
$7FFF. Since it is the last block, an extra $7FFF is appended. 
The complete region structure would look like this: 


Data Y X Pixels set Block 
10 10100 $7FFF-> 10 10-100 Block 1 
80 100 200 $7FFF-» 80 10-200 Block 2 
100 10 80 $7FFF-> 100 80-200 Block 3 
200 80200 $7ЕЕЕ-> 200 None Block 4 


$7FFF 
721 


In hexadecimal: 
000A, 000A, 0064, ТЕРЕ, 0050, 0064, 00С8, TFFF, 
0064, 000A, 0050, ТҒҒҒ, 00С8, 0050, 00С8, TFFF, TFFF. 
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From: rajohnson (Robert Johnson) 

Subject: Inside Mac & Palette Manager 

Well, I finally got my long awaited ‘final’ copy of Inside 
Macintosh У, and I had very mixed feelings about the fruits of my 
waiting. On one hand,there was a lot of new information not in 
my APDA pre-release, and for the most part it seemed finalized 
and not contradictory (vs the aforementioned pre-release). But 
in no published documents have I found the trap numbers for the 
Palette Manager routines. For the method that is encouraged 
(almost at gunpoint) to access colors on the Mac II, the Palette 
Manager should receive extensive coverage. Even in the equates 
files included on floppy with the APDA pre-release, there is no 
mention of these trap numbers (I need trap numbers because I 
program mainly in assembly). Luckily, there is a place that I do 
have access to this information: MacsBug has a complete listing 
of all Macintosh trap numbers. Unfortunately the only informa- 
tion MacsBug gives to ‘wh <trapName>’ is the address of the 
routine patch in RAM. 

Using the ‘f’ command, I was able to locate where in the trap 
table at $E00-$1E00 the particular routines were referenced, and 
each entry in this table is easily related to a trap number. In this 
way, Ihave compiled the list of unpublished trap numbers below. 


Palette Manager Trap Calls 


InitPalettes АА90 AnimateEntry АА99 
NewPalette АА91 AnimatePalette AA9A 
GetNewPalette AA92 GetEntryColor AA9B 
DisposePelette АА9З SetEntryColor AA9C 
ActivatePalette AA94 GetEntryUsage AA9D 
SetPalette АА95 SetEntryUsage AA9E 
GetPalette AA96 CTab2Palette AA9F 
PmForeColor АА97 Palette2CTab AAAS 
PmBackCo lor АА98 CopyPelette AAA 1 


PROCEDURE CopyPalette(srcP11t,destP11t:handle; 
srcEntry, destEntry, count: integer ); 


is not documented anywhere that I have seen, but I deduced 
the preceding Pascal interface by disassembling the RAM patch. 
The procedure copies count entries from srcPllt starting at 
srcEntry to destPllt starting at destEntry. In the process of 
disassembling the patch, I found a slight bug in the code (I guess 
it’s not that harmful in a non-documented (гар). When 
srcEntry+count > pmEntries in srcPllt, it looks like the attempt to 
decrease count by srcEntry+count-pmEntries is botched because 
of a sign error (they subtracted pmEntries-srcEntry-count from 
count rather than adding it to count). If one is careful not to have 
srcEntry+count exceed pmEntries, all should be fine. This is 
such a useful routine; I think Apple should document it (and 
correct it). 

Also, some other documented routines are missing their trap 
numbers in IM V, although they are listed in the APDA equates 
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files on floppy: 
CloseCPort АА02 GetCTSeed АА28 
OpenCPicture АА20 SetStdCProcs AME 


Of these, CloseCPort has been included in ClosePort 
(A87D) and OpenPicture (A8F3) will do the work of OpenCPic- 
ture when the current grafPort is color. 

There is another trap I haven't seen anywhere: Update- 
PixMap (AA38). Upon disassembly, it turns outto be justa RTS! 
Guess another system update is in order. 


From: rick (Rick Boarman) 

Subject: New ROMs 

It seems that the new MacII ROMs cause several problems: 
TMON dies ahorrible death. Version 2.8.1 is supposed to fix this. 
Macsbug 6.0 also dies. Dimmer 1.0B2 bombs. Anyone else have 
any problems yet? 

From: ада! (Alan Dall) 

Subject: LaserWriter 

Someone that I know has a Macintosh, a Laserwriter and 
many other computers of many types. They want to connect the 
Laserwriter up to a PC and then send their Mac output to the PC 
to be downloaded to the Laserwriter. They have created 2 files 
with the print option. One with command-k to generate the 
postscript header and one with command-f to generate the files 
themselves. When they transfer these files directly to the 
Laserwriter, all of their output comes out backwards. Does 
anyone know what they need to do to make their output come out 
right? [You only need to use the cmd-K option, which creates both 
the file itself and the LaserWriter Prep header. That single file 
can then be downloaded to the printer and it should come out 
exactly like it would from the Macintosh. Something or someone 
is resetting something in the LaserWriter or else the prep file is 
not being executed properly so that the page orientation setup is 
being modified. -Ed] 

From: ewer (Bill Ewer) 

Subject: Display PostScript 

Does Adobe expect anybody to getall excited about Display 
PostScript? Му first impression is that it’s deadly slow. I 
estimate its max drawing speed is about 3K vectors a second. 
Does anybody know the exact drawing rate. How about Quick- 
erDraw; how fastis it? The reason I ask is in advising a client on 
what display drivers they should include with their new color 
graphics app they are pushing for Display Postscript and I'm 
telling them its a waste of time and money. Any thoughts out 
there. [I used to think like you until I heard Andy Hertzfeld say at 
the San Francisco Expo that Display Postscript is powerful and 
fast and that Apple should use it. That changed my mind real fast. 
If Andy says it is fast, then you can bet it’ s worth looking at. I saw 
it and it looked pretty good to me.I think Apple should make it an 
option. QuickerDraw is what Apple should have done in the first 
place if they had hired programmers who knew assembly lan- 
guage like Andy does, instead of Pascal coders. -Ed] 

From: powerhopeful (Power Hopeful) 

Subject: Display Postscript 
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My hope is that сап be avoided. Regardless of its features, 
Speed, or anything else, I think that its owner's licensing fees and 
behavior are ridiculous. 

From: ericj (Eric Johansen) 

Subject: Laserjet and Mac 

To those of you who responded to my query regarding the 
Macand the HP Laserjet, thank you. Here's the results. The goal 
was to find a solution to make the Laserjet, Mac compatible, and 
put it on the Appletalk network, so everyone could use it. 

There is a driver called ProPrint, by Creighton Develop- 
ment. They're mentioned in this month's MacUser. I called 
them, the number's been disconnected, with no new number 
listed, i.e. they're history. One down. [That was Chris Derossi' s 
old place of employment! Chris is now at Apple Technical 
Support. -Ed] 

There is another driver by Softstyle called Printworks for the 
Mac, Laser Version. It kind of works, but I hate it. It was а pain 
to install. It uses 3 DA’s to control such things as Font adjust- 
ment, Color Adjustment, and Spool adjustment. The Font 
adjustmentDA is for matching screen fonts with what's available 
on the Laserjet. There's no postscript on the Laserjet, so it can't 
build different size fonts, other than what's supplied in ROM, 
Font Cartridges, or downloaded into RAM via a PC. The Color 
adjustment is automatically installed, even though on the “Laser” 
version, there is obviously no color printing. The Spooler that is 
included uses RAM. Uh-huh. It is not compatible with TOPS, 
both old and current versions, nor is it compatible with any other 
spoolers. In short it is a real pain in the rear end. The good thing 
I can say for them, is that their tech support people are pretty 
good, and more than willing to help with any problems. Two 
down. | 

Another option was the QMS board that makes the Laserjet 
postscript compatible. It's expensive, (around $2500), and it's 
not Appletalk compatible. Three down. 

The Grappler LQ. One of you mentioned it here on the 
board. I'd heard about it before and they demo'ed it at 
MacWorld, but it's not shipping until March. However, after 
talking with the sales people and the tech support people at 
Orange Micro, this seems to be solve the compatiblity issue. The 
Grappler LQ enables the Laserjet to mimic the Apple 
Imagewriter LQ. You use the Imagewriter LQ driver that Apple 
is shipping, and Orange Micro's serial to parallel converter. The 
Laserjet “smooths” out the 240 dpi of the LQ and prints it at 300 
dpi. Going by some sample copy I saw, this looks pretty good. 
Apparently this thing will make most popular parallel printers 
Work with the Mac. 

As for putting the Laserjet on the Appletalk network, I found 
the NetSerial by Shiva. This little sucker is expensive, (retails 
$399), but it works. It will put any serial device on the Appletalk 
network. [About time someone invented that! -Ed] 

Since the Grappler LQ is a serial device, the combination of 
these two should work. God willing. 

From: jsurreal (Roy M. Lovejoy) 

Subject: List Manager Bug.. 

Iran into what I think is a related bug in the List Manager.. 
This was my problem: I hadan application that created a window, 
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then added a List to that window. When I read ina specific 'file' 
it would add the data to that list, when I closed that ‘file’, I did an 
LDispose, *BUT I KEPT THE WINDOW!* after three LNew- 
LDispose’s оп one window, the program hung... Delving deeper 
with a debugger, I found that it was hanging in my UpdateProce- 
dure, during a DrawControls(MyWindow) (My Window also 
had buttons} .. Further investigation revealed that DrawControls 
was stuck in a <get-this> CIRCULAR LINKED LIST OF 
CONTROLS. It seems that either LNew or LDispose (probably 
the former) does not insert (/add) the List’s scroll bar controls 
properly to the windows linked list of controls... My solution was 
simple.. I just deleted the data, not the ListHandle. 


From: rguerra (Rich Guerra) 

Subject: Terminal Emulation in LSP 

I'm fooling around with Lightspeed Pascal trying to write a 
simple terminal program. I’ve got the basics working; now I 
want to add some other niceties such as screen buffers. Does 
anyone know how this is accomplished? To keep one huge 
bitmap corresponding to the number of screens around would 
seem ridiculously expensive in terms of memory. It seems from 
а previous message that using TexEdit is prohibitively slow. So 
how are buffers done? Perhaps incoming characters could be 
written to a chunk of handled memory and when a user wants to 
scroll back to see the previous screens, one could calculate offsets 
into the memory and copybits the characters into a bitmap that 
corresponds to the single screen normally displayed. Does this 
sound reasonable? Any thoughts, comments or suggestions 
would be greatly appreciated. 


From: frank (Frank Henriquez) 

Subject: Re: Terminal Emulation 

I've written some generic low level serial I/O routines in 
assembly, and a terminal emulation program (both in Turbo 
Pascal and assembly) that makes use of these routines. My first 
version used DrawChar to display the text on the screen. 
DrawChar is fast, but it's a pain to do simple things like back- 
space. 

TextEdit is slow, even with assembly language, but there is 
atrickthat'll let TextEdit keep up with data coming in through the 
serial port: make the default serial I/O buffer larger (the default 
setting is something like 64 bytes). By making the buffer 1 or2K 
big, TextEdit will not cause the serial drivers to loose data, and 
you can go to pretty high speeds; I’ve tried it at up to 9600 baud 
with no loss of data. I’m thinking of sending it all in to MacTutor, 
since accessing the serial ports has always been an unpleasant 
task and it seems to be one of those perennial Mac programming 
questions. [Please do! -Ed] 


From: mark.chally (Mark Chally) 

Subject: SetiText from a Desk Accessory 

My main question is: Why does SetI Text respond differently 
from within a desk accessory than it does from within an 
application? I wrote an application model of my "HexFlags DA” 
before doing the DA version. When I used SetIText to set the text 
of an edit Text field, it worked fine with the application. How- 
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ever, when tried it from the DA, I found that the contents of the 
field were getting updated, but the CHANGE was not getting 
drawn. ІҒІ forced an update on the field, it would happen 
correctly. This was very frustrating as the performance of the 
Desk Accessory “looks quirky" as I found the "best way" to 
handle the situation was to do an “EraseRect” on the field’s Rect. 

I suppose I could do something more elegant, but maybe 
someone else can more accurately explain the problem and an 
effective workaround or fix? I can supply the source code in full 
to Apple Tech support for both versions of the program if it will 
help. 


From: Isr (Larry Rosenstein) 

Subject: Re: бейТехі from a Desk Accessory 

Here's the problem. SetIText does get passed the window. 
Therefore the trap has to scan through all the window looking for 
dialog windows. For each dialog window, it looks through all the 
items to see if the handle matches. 

When it finds the right dialog & item it can update the screen. 
The text is always inserted into the handle, even if SetIText can’t 
find the item to do the update. 

The problem is that dialog windows are identified by a 
special value in the windowKind field. In a DA, this field 
contains the negative of the DA refnum. The solution is to save 
the windowKind and set it to dialogKind (=2) before calling 
SetIText. Then restore it afterwards. 


From: atom (Mark Adams) 
Subject: mpw LDEF's 


Does anyone have any example code for writing a LDEF | 


resource from MPW Pascal? I have converted code from 
Lightspeed pascal, and have gotten it to compile into a LDEF 
resource, but every call to the Idef by the list manager gives me 
an illegal instruction trap. I've looked around with Tmon, and 
from what I can tell, the pascal compiler is not setting up the code 
so that the first instruction in the code is the first instruction to 
execute. There seems to be garbage at the beginning of the code 
resource. 

I did notice that if I took the variable declarations out of the 
LDEF procedure heading, (made it just Procedure MyListDef;), 
it executed the code correctly. Except of course then I had no 
variables being passed to the routine, so I couldn't do much. 

Is there a compiler option or linker option that I need to set 
to getitto setup the entry codecorrectly with a code resource that 
need parameters? or can it not be done from pascal? 


From: rdclark (Richard Clark) 

Subject: MPW Pascal LDEFs 

Look at Tech Noteit1 10 “MPW: Writing Stand alone c Code 
in Pascal." BTW, you don't have to create a LDEF as a seperate 
resource... if you look in the List Manager chapter of М4, you'll 
see that one of the fields documented there is a Handle to your 
LDEF procedure. You can make the LDEF a procedure in your 
program, then create a “dummy” handle (the size of a pointer) 
which points to your procedure. Then install this handle into the 
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List's record. (confused?? Need the tech note?? Send me eMail 
with your SnailMail or FAX address, and I'll send a copy of the 
tech note and some sample code. Alas, the sample is in Light- 
speed C, but it shows some of the tricks I'm describing.) 


From: Isr (Larry Rosenstein) 

Subject: Re: MPW Pascal LDEFs 

Beware of creating "fake" handles. If you make a handles 
that's simply a pointer to a pointer to your procedure, you won't 
rununder A/UX andrisk being incompatible with future systems. 
The correct way is to create a 6-byte handle with NewHandle and 
putaJMP $xxxxx instruction in the handle, which jumps to your 
procedure. 

Also, if you are doing a WDEF in this way, be careful to test 
it with MultiFinder. When MultiFindercalls a WDEF, it does not 
swap in the process associated with the window. Therefore a 
WDEF cannot easily access global variables. 


From: atom (Mark Adams) 

Subject: Idef handle 

I used to do it that way (with a fake handle), but had lots of 
problems when I started allocating a lot of memory. And I never 
did feel right about it, since it isn't really the way to do it by 
Apple's guidelines. 

From: the cloud (Ken McLeod) 

Subject: STRS resource 

I have noticed that LightspeedC stores strings declared in a 
program (as opposed to strings gotten by GetString/GetInd- 
String) in a resource of type ‘STRS’. The format appears to be 
quite simple: a length byte followed by the string itself. However, 
changing one of the strings and adjusting the length byte accord- 
ingly (using ResEdit) instantly rendered the program unuseable. 
Is the size of the STRS resource taken into account somewhere 
else (like in a CODE segment, perhaps)? 

From: dhill (David Hill) 

Subject: Lightspeed C Multifinder bugs 

Here is a list I have put together of problems I have been 
having with Lightspeed C under Multifinder. 

1. On compile - gives an “illegal token” error in Mactypes.h, will 
not compile until I quit and re-run lightspeed 

2. On Quit (or ShutDown) - gives a "Volume not found - 
PrintMgr.h" error, need to hit quit again for it to quit. 

3. On compile - gives a system error $7FFF before the compile/ 
lines dialog even appears, need to reboot. 

4. On run - doesn't recheck the available memory, will not allow 
you to run even if you have plenty of memory currently 
available, need to quit lightspeed. 

This is just to see if I am the only person having problems 
with lightspeed under Multifinder and hopefully to see some of 
these fixed in the next update. I am using Version 2.13 and have 
never had a problem running under finder. 

From: dirck (Dirck Blaskey) 

Subject: Re: Lightspeed C Multifinder bugs 

Ihave no problems with 15с v2.13 under multifinder. Maybe 
your copy is corrupted. [Current version is 2.15! -Ed] 
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From: Steve Seaquist 

Subject: New Virus Discovered 

There is a new virus going around that affects MacDraw, 
Excel and others. It also leaves nasty messages on AppleTalk. 
This one is not peaceful, so watch out forit! It installs itself in the 
segment load table, after adding one to the number of code 
segments. It installs itself as the last code segment, which is one 
greater than the first unoccupied segment. It intercepts the start 
of program pointer in the segment loader, to point to itself so the 
segment loader launches it with a segment load. This comes per 
the Washington Apple Pie Bulletin Board, where the virus was 
first isolated. Itis believed to have started in February of this year, 
but may date back as long as September of 1987. It also affects 
printing and set start-up options in the Finder. It is known to 
corrupt Excel files. It changes the type and creator of the note pad 
and scrapbook files such that the system folder sees them as plain 
document icons. It creates two invisible files called scores and 
desktop in the system folder. In the system file, watch out for inits 
of ID 6, 10 and 17. In the bogus system folder desktop file, there 
isan ATPL resource of ID 128, anda DATA resource of ID -4001 
and INIT resource of ID 10. In the notepad file, the file type is 
changed to INIT and the creator to ZSYS, which is backwards. 
The virus knows about ResEdit and can re-install itself if you 
patch with ResEdit. Recommended solution is to restore all 
applications and system files that have been infected. The effect 
of the virus is to place bogus error messages in various appletalk 
dialogs, especially dialogs concerned with printing, thereby 
refusing to print over appletalk. The virus is detectable by 
vaccine, a commercial virus detector by CE Software, but not 
until after the infection. This is the same virus recently described 
in InfoWorld and MacWeek articles. 

From: davidk (David Kosiur) 

Subject: Fractional font widths 

I just ran a cdev called Who's Who and it told me that 
fractional fonts was disabled on my Mac II. Question is — do any 
programs use fractional font widths? If so, which ones? Thanks. 
[I believe Pagemaker uses fractional width tables. Ed] 

From: gking (Greg King) 

Subject: SCSI comments 

I just got another contract for a SCSI driver so I decided to 
update one that I wrote last year. After re-reading Jórg 
Langowski's article in the Jan/88 issue of MacTutor I decided to 
try out some of his suggestions. 

One suggestion was to replace my looping TIB (transfer 
instruction block) with one that transfers all the data in one pass. 
It worked fine on my Mac Plus at home but failed miserably on 
my Mac Il at work. The drive would always come up with a “Disk 
needs minor repairs" message and you could not read or write to 
it unless the operation was performed in extremely small chunks 
(«512 bytes?). Re-inserting the looping TIB allowed the driver 
to work on a Mac II. It is possible that the Mac II is so fast that 
a single instruction transfer overwhelms the drive and that a 
looping TIB gives the drive enough breathing room. Even with 
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this deliberate degradation in performance a Seagate ST251N is 
best formatted with a 1:1 interleave on a Mac II. I have also found 
no difference in performance between the two TIB types on a 
Mac Plus. 

Also, my July/87 copy of Tech note 96 contains no injunc- 
tion against complex TIB's. What it does warn against is 
performing multiple SCSIRead's within a single SCSI command 
sequence (SCSIGet, SCSISelect, SCSICmd, SCSIRead/Write, 
and SCSIComplete). 

PS: The documented word order for the longint result from 
KeyTrans in IMS is backwards. 

From: jimr (Jim Reekes) 

Subject: Re: SCSI comments 

Makes me smile. Greg, you've just realized *some* of the 
difficulties in developing SCSI drivers for the Mac. The Mac II 
will perform nearly 98% of the SCSI spec (about 1.4MB/sec). 
Trouble is, most drives will not come close to this speed. The 
251Niscloser to 800KB/sec. Blind operations are what typically 
hangs up the transfers. But I'm confused by some of your 
statements, I would have expected the Mac II to perform the 
operation and the Мас+ should have failed.(?) Also, I didn't 
understand what you meant by *«512 byte transfers". The 
smallest transfer would be a single block which is at least 512. 
bytes. Butto agree with you on your assumption, it is possible to 
overwhelm some drives, such as the high capacity SCSI Rodime 
drives which cannot handle a blind transfer. It's not the TIB or 
that it is a single instruction that overwhelms drives, it is the 
amount of data being transferred and the speed of that transfer. 

From: Inedry (Larry Nedry) 

Subject: SCSI comments 

Greg, You must have made an error somewhere in your 
code, because I have written a SCSI driver using a non-looping 
TIB that works on all of the Macs. I have been using it with very 
fast drives so that may be the difference. 

From: dirck (Dirck Blaskey) 

Subject: floating windows 

The tear-off menus in the product I'm working on use 
floating windows. I don't know what the recommended method 
of doing this is, but I patched 3 traps to get it to work. There's 
also a couple of hooks into the event loop for fun things like 
cursor maintenance (automatically sets up the arrow cursor 
when over the menu) and other fun things like updating. The tear 
off menus use bit maps and rectangle lists in the resource instead 
of a separate mdef with drawing code for every different menu. 
In other words, it's a generic graphic tear-off menu mdef. If there 
continues to be a lot of interest and/or confusion on this subject, 
perhaps I can obtain permission to publish the code, maybe in a 
MacTutor article or on the mhdl. [Please see the very good article 
in the April issue of MacTutor on tear-off menus and floating 
windows done in C. This article had the blessing of Apple 
Technical support, which reviewed it before publication so it is 
a sanctified approach. -Ed] 

From: тако (Mark Guidarelli) 

Subject: New MAC Il ROMs? 

Hmmm, we got 3 new Mac Ils in at work this week and 
TMON does not function on them. We have version 2.8 and it 
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works fine on the other Mac IIs there....so I'm wondering what 
the difference is. Has Apple issued some new ROMS for the II 
finally? If so what did they fix/change? The NuBus problem 
perhaps? [Гуе heard that there is а ТМОМ 2.8.1 that fixes 
whatever the problem is. -Ed] 

From: brett (Brett Bilbrey) 

Subject: New Mac ІІ ROMS 

Apple has seeded some developers with new ROMS and the 
newest Mac IIs rolling off the production line have new revs. Ап 
earlier post referenced TMON working or not working on differ- 
ent Мас IIs. Well first, the current rev of TMON is 2.8.1, and if 
you want to find out what version of ROMS you have in your 
МасП use ‘sGetInfo’ or ‘Slot Investigator 1.2’. If you have the 
old ROMS you will see an error or old ROM report, if you have 
newer ROMs the version will be displayed. Note in the newer 
ROMS slot0 now refers to the CPU! (i.e. 68020) Now before you 
run out screaming “I need new ROMS”, WAIT. If you want to 
upgrade your МасП, wait till QuickerGraf and 24-bit QuickDraw 
become real. For now let the developers play with their alpha 
ROMS and work their bugs out. So far, nothing that has been 


changed is useful yet, no one uses 32-bits and the rest is cosmetic. ` 


When you will need 32-bits, a real ROM set will be available. 

From: bilir (Bill Rausch) 

Subject: MacWrite 5.0 

A guy in my building just got MacWrite 5.0 (and upgraded 
his 128!!! toa 512KE) and it doesn't perform as advertised. The 
spell checker won't work on a 512KE. If you start MacWrite, 
create a new document, and spell check it, it might work - 
sometimes did and sometimes didn't. If you do any file opening 
or saving you are out of luck. The error message says the 
clipboard is too large - this even if only a single word is selected 
for checking. Either poor testing or false advertising to claim the 
program works on a 512KE. 

I did take his disk down the hall and it works great on 
MacPluses and SEs. Also, it failed on another 512KE with 
external 800K floppy and failed on a Hyperdrived 512KE. (The 
first 512KE had an HD-20 attached.) 

Does anyone have any comments? Our dealer didn't. 

I made sure to test it with a clean, Apple System Tools disk 
for Finder 5.3 and System 3.2 with no extraneous INITS, etc. and 
it didn't matter. The symptoms were always that everything 
except the spelling checker works fine (and that of course is why 
he wanted the latest version). 

I'm trying to talk him into upgrading again to a MacPlus for 
various reasons and I think he'll do it, but this is still bad stuff 
from Apple. 

From: billr (Bill Rausch) 

Subject: Re: MacWrite 5.0 

After posting my previous message I talked with Claris tech 
support (nice guy by the way). I described the problem, he 
admitted that they had one and had been looking for a solution 
unsuccessfully. We talked for a while and then he got real 
interested when I said that I could repeatedly duplicate my 
problems. Apparently I was the first complainer who could 
demonstrate a repeatable failure or success pattern. After taking 
a bunch of notes, he left to go try replicating my problems. 
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I got a call back the next day from a lady just going down 
a list of names. They found the problem and will send out new 
disks to 1) everyone? or 2) everyone who complains? - I'm not 
sure which. 

She didn'tsay but my suspicion is that they forgot something 
simple like unloading segments notin use. They' ve implemented 
the spelling checker as a captive desk accessory and use the 
clipboard to pass the words back and forth. I really did like iton 
larger machines, by the way. It seemed pretty fast and very easy 
to use - just like MacWrite. 

From: rick (Rick Boarman) 

Subject: Help! 

Help!! Does anyone know how to get small text edit boxes 
to work correctly with small boxes? I need to put Geneva 12 
characters in a box that's 9 pixels high. No matter what I change 
the font Ascent and line Height to, it doesn't work. The text either 
jumps when I hit tab or draws wrong on an update event. What 
gives? [Can't be done with text edit. Use DrawString first, then 
draw box on top. -Ed] 

Also, does someone know how to read PostScript fonts? We 
need to be able to read a font file and process the characters in the 
file in a random access method. Adobe hasn't been much help in 
this (They've been *unfriendly* about it actually). 

From: dhill (David Hill) 

Subject: printing problems 

I am having trouble with my printing routines. 

WhatIam doing is calling prOpenDoc, prOpenPage etc. and 
then the same code that updates my windows. Iam also calling 
SetOrigin tocenter the graphics on the page. Whathappens is the 
first page prints out perfectly, but any subsequent pages (running 
the same code - with different data) are missing a big chunk - they 
have a big white rectangle in them. This happens for different 
print loops as well. I think it might be a problem with SetOrigin 
messing up the VisRgn or clip rect or something. [Try not using 
SetOrigin, and instead position on the paper directly, as you 
would on the screen. Also, you might look at the Plotter program 
in the Feb issue of MacTutor which printed a hairline plot using 
code similar to what you are doing. -Ed] | | 

From: rsiegel (Richard біедеі) 

Subject: Re: Lightspeed C Multifinder. 

Youcan increase (or decrease) the memory allocated to your 
project by putting a SIZE resource in the *project* file. Putting 
itin the resource file won'tcut it, since the SIZE gets used before 
the project resource file gets opened. 

From: alpha (Jean Thomas) 

Subject: TRACKCONTROL/ASM 

I have two questions on TrackControl: 

Does anyone know the proper way to get to use action procs 
with TrackControl from assembly? What I'm doing now gener- 
ates ID=1 error. 


clr.w  -CP) 

move.|  VertScrol1Ca52,-CSP) 
move.]  Point(a5),-CSP) 

LEA DoThings, a8 

move.]  80,-C(SP) 
_TrackControl 
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move (SP )+, d6 
DoThings: 
move t 1, -CSP) 
_ЗузВеер 
move.1 
ітр (ай) 


(SP)+,a0 


Isthistheright way? (Ithink it's time for Pascal..) The above 
question is for manipulating the up and down arrows in a scroll 
bar. The action proc is DoThings. 

I remember reading in IM that whenever the user clicks in 
either the up or down arrow, you should check the cursor to make 
sure it is still in the arrow. If itis not, scrolling should should stop. 
Is this done with TestControl? How would you incorporate it into 
the shell above. Am I dumb for trying to do this in assembly, or 
what? So much housekeeping... Thanks for any help. 

From: frank (Frank Henriquez) 

Subject: Re: TRACKCONTROL/ASM 

Part of the problem in your code is this: 


LEA DoThings, ag 
move.1 ай,-(5Р) 


it should be this: 
pea DoThings 


This is from Dan Weston's “The Complete Book of Macin- 
tosh Assembly Language Programming, VolumeT", page 189. If 
you're doing any sort of assembly language programming on the 
Mac, Dan's books (volumes 1 & 2) are almost as important as 
Inside Macintosh. APDA has them, so do some bookstores, like 
the B. Dalton chain, and the UCLA book store. 

From: mark.murphy (Mark Murphy) 

Subject: Re: using Imagewriter 1 built-in fonts 

To send ASCII directly to the Imagewriter in 4D, use Set 
Channel and Send Packet. There is an example to set the serial 
port to the Imagewriter on page 160 in the Command Reference 
manual. The example shows the call as Set Chan- 
nel(0;10+3072+16384+8192). Then all you should need to do is 
call Send Packet(strexpr). Send Packet is documented on page 
157 of the same manual. Hope this helps! 

From: rusty (System Administrator) 

Subject: Funny Drive Problems 

Anyone having any sort of Hard Drive problems, bring them 
outin the open. One thing I' ve found is that many people have the 
same sortof problems, but no one talks much about them. Maybe 
we can save someone some grief. 

One problem I’ve seen/heard happens fairly frequently (not 
frequent in general, but frequently in the scope of problems in 
general)- 

The (MiniScribe?) 3.5" mechs in the newer Mac SE's are 
failing in the same way: Drive isn't recognized at all, but the 
drive blinks SOS, so most of its controller must be okay. Has 
anyone ever been able to recover data after a problem like this? 
What exactly is failing? The actual SCSI VLSI? 

From: rusty (Rusty Hodge) 

Subject: Accelerated Drives 

According to Radius (in their Accelerator manual), certain 
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hard drives will do unnatural things to themselves when booted 
if the accelerator is active. Anyone know which drives these are? 

From: davidw (David Whiteman) 

Subject: Re: Accelerated Drives 

Rusty, among other drives, the Radius card is not compatible 
with the non-SCSI hard drives: Tecmar, MacBottom, Paradise, 
Apple HD-20. 

From: sam (Sam) 

Subject: Re: CMS SD-60 (ST-277) 

If you are having trouble getting your Macintosh II to boot 
from a Seagate ST225N or 277N it might be due to the amount 
of time the Seagate requires to pull the heads back to the stop at 
track 0 just after power-up. The Finder will update the volume 
info at the last block of the disk - 1 when the volume is unmounted 
which in Seagate’s case will leave the heads at the farthest point 
from track zero. The drive moves the heads slowly at power-up, 
because the heads are not parked, it doesn’t know over which 
track they lie (it’s also not a good idea to ram the head assy into 
the stop at full speed). Anyway, to the point. The Mac II will wait 
I think it’s 20 or 25 seconds for any active drives to respond. 
Guess what.... the ST225N takes about 2 seconds longer than the 
Mac will wait — I'm not sure about the 227. Could this be the 
source of the non-booting SD-60 ?? Is the SD-60 an internal 
drive? If not, powering-up the drive a few seconds before 
booting the Mac will fix the problem. 

From: jimr (Jim Reekes) 

Subject: Re: CMS SD-60 (ST-277) 

Huh? I don't understand your point. The SD60 is a 277N. 
The heads do recalibrate during every power up cycle. I guess it 
does take about 20-30 seconds for this to complete. The Mac II 
will continue to check the SCSI bus for a device to respond until 
the first one does. This means that no matter how long it takes the 
external drive to “соте ready', the Mac II will continue to 
attempt to boot from it. 

This is NOT the case with internal drives. The above 
situation is also (darn it) not going to work if you insert a floppy 
to boot from before allowing the hard disk enough time to spin 
ready. 

If you have the situation where you wish to boot from an 
internal hard disk and also have a bootable external hard disk, 
then you should set the internal's ID to 0. This will cause the 
StartupManager to allow a longer ‘grace period’ for the internal 
tocome up to speed. Otherwise, simply remove the system folder 
from the external. (Itis a bad idea having more than one system/ 
finder anyway.) 

If you turn on the external drive and then immediately insert 
afloppy to bootthe Mac from, then you did notallow enough time 
for the drive to spin ready. This is true for all Macsand hard disks. 
If you turn on the Mac II with an internal hard disk, and quickly 
insert a bootable floppy, then you've got the same problem 
above. 

From: d.goss (David Goss) 

Subject: Time of Day 

Does anyone know how to tweak the time-of-day clock, e.g. 
to slow it down ог speed it up? Some computer clocks have а 
trimmer capacitor for that purpose, but I don't have any docs on 
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the Мас and haven't taken it apart to look. 

From: powerhopeful (Power Hopeful) 

Subject: PMMU 

I got the 16 mHz PMMU from Motorola ! 

But I also have a SLIGHT problem: I can't seem to locate 
where it belongs on the Mac II motherboard. I can only see 2 
empty sockets, both near the MPU, but neither is big enough to 
accommodate the PMMU, which is the same size as the 68020. 

From: wayne (Wayne Correla) 

Subject: PMMU/HMMU 

The PMMU replaces the HMMU chip which is a big black 
square chip that sits just to the rear of the 68020 at location U67. 
Be sure to observe the polarity of the chip by noting the dot, 
notch, or key at pin 1. As you face the computer from above and 
the front, the pin 1 location is in the South East Corner. When 
removing the square package IC, lift each side slightly until it 
pops out. Remember not to break/lose/spindle/fold/mutilate this 
chip as you will need to put it back in its place if your Mac II main 
logic board ever needs to be serviced or replaced. To insert the 
new 68851 PMMU ІС locate the gold colored “Ү” pointing 
towards one of the corners. This is ріп #1. orient that corner so 
that it points toward the South East corner of the socket and lay 
it in the socket. If you are confused, look for the number ‘1’ 
silkscreened in white on the logic board. Now take your thumb 
and press down evenly on the center of the IC. 

From: powerhopeful (Power Hopeful) 

Subject: PMMU 

Thanks, I was able to install it. 

BUT.. 

I'm having problems getting the Mac to use 32-bit address- 
ing. I've messed around with it for awhile and have made a few 
conclusions. I know there was a bug reported concerning inabil- 
ity to recognize 32-bits on NuBus. Could this same bug be 
preventing acknowledgement of 32-bits of address in main 
memory? 

The byte at $CB2 indicates which addressing mode is in use. 
Attempts to change that byte to $01 directly will cause a system 
freeze-up, which is different from a system error in that it cannot 
be handled by Macsbug and there's no info or recovery. The 
routine _SwapMMUMode is patched to a location in ROM, 
where there is right before your very eyes an instruction that 
writes an illegal value to the PMMU. In that routine the machine 
will tolerate the changing of the $CB2 byte. But when an attempt 
is made to write #0 to the PMMU reg, the machine again freezes. 

[The Macintosh OS cannot use the PMMU because it 
cannot work in 32-bit mode due to 16-bit addressing restrictions 
in the memory manager and segment loader portions of the 
ROMS. Only А/ОХ сап use the PMMU. -Ed] 

From: powerhopeful (Power Hopeful) 

Subject: Slots 

Anyone know how I can directly access the Mac II slots? Is 
the fact that any of the (24- OR 32-bit) addresses listed in IMS 
give me a bus error due to the bug? 

From: cderossi (Chris Derossi) 

Subject: Re: Slots 

First of all, you need to know that the Mac II slots are not 
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numbered in software as 0-5 or 1-6. Instead, they are slots 9-E. 
This means that the 24-bit address of the card in the first slot is 
900000-9FFFFF. In 32-bit mode, its address space is F9000000- 
F9FFFFFF (16 times as much). 

You can experiment with this easily. Assuming that you 
have an Apple video card in the first slot (slot 9), use TMON to 
change the value at the address 900020. This will affect the first 
pixel(s) on the screen directly. [The first 32 addresses are used as 
registers for the TFB chip.] You should not get a bus error. 

From: philk (Philip Kutzenco) 

Subject: Mac ПІ screen shake | 

My МасП with Apple Color Monitor and Apple Color 
Display Card with extended memory has a problem. Most of the 
time, the display sort of gently shakes - maybe wavers is a better 
word. It doesn't seem to have anything to do with accessing the 
drive (a CMS PRO 102). It happens even when I'm just looking 
at the desktop. I don't think it is power related as I'm am on a 
power regulator. Can someone help? I really don't wantto lug it 
to my dealer and leave it hoping he knows what to do. By the way, 
degaussing has noeffecton the problem. (My Mac II has the same 
problem, usually at start-up. -Ed] 

From: steve.sheets (Steve Sheets) 

Subject: Mac // Video Card 

Does anyone know how to change where the Mac //’s Screen 
Pixmap is pointing at. Basically I want to try some video page 
switching. If you had a Mac // video card (fully stuffed for 8 bit 
pixels) set for 1 bit pixel mode, you should have enough memory 
on the card for 8 seperate PixMaps. Someone awhile back told 
me that the hardware can do this, how do you do it in software? 

From: cderossi (Chris Derossl) 

Subject: Re: Mac // Video Card 

Having not actually tried this, I know that I am missing 
some details, but the basic thing you will want to do is this: 

Create a new GDevice with the NewGDevice call. Copy 
almost all of the fields from the MainDevice. (But you'll want to 
use [I think] a refNum of 0 and a mode of -1 to indicate that this 
is NOT a video card.) | 

Make your phoney GDevice correspond the the MainDevice 
in global coordinates, and then make it active. Make the MainDe- 
vice inactive. This will make QuickDraw draw to your device 
instead of the screen. 

If you want, youcan experiment with using different (maybe 
larger) rectangles for your GDevice. When you do this, you are 
going to confuse a lot of routines (which is why Monitors can't 
change logical location until reboot). I suspect that the best time 
to do this will be at INIT time, and you're going to have to mess 
with some low memory globals (like the screen size ones) if your 
device doesn't match the main device. 

Finally, you'll need to create a PixMap that goes with your 
device, and allocate some memory for it. Then, when you want 
to display the contents of your device on the monitor, use 
CopyBits. You can even keep your PixMap in some fixed mode 
(like 8-bit/pixel), and CopyBits will covert to whatever PixMap 
applies for your monitor. 

As I said, this is sketchy, kludgey, and unsupported. But if 
you get it working, I'd love to see it. 


O The Definitive MacTutor, Vol. 4 


From: егіс) (Егіс Johansen) 

Subject: Macs and Laserjets 

To those of you who responded to my query regarding the 
Mac and the HP Laserjet, thank you. Here's the results. The goal 
was to find a solution to make the Laserjet, Mac compatible, and 
put it on the Appletalk network, so everyone could use it. 

There is a driver called ProPrint, by Creighton Develop- 
ment. They're mentioned in this month's MacUser. I called 
them, the number's been disconnected, with no new number 
listed, i.e. they're history. One down. 

There is another driver by Softstyle is called Printworks for 
the Mac, Laser Version. It kind of works, but I hate it. It wasa 
bug to install. It uses 3 DA's to control such things as Font 
adjustment, Color Adjustment, and Spool adjustment. The Font 
adjustment DA is for matching screen fonts with what's available 
on the Laserjet. There's no postscript on the Laserjet, so it can't 
build different size fonts, other than what's supplied in ROM, 
Font Cartridges, or downloaded into RAM via a PC. The Color 
adjustment is automatically installed, even though on the “Laser” 
version, there is obviously no color printing. The Spooler that is 
included uses RAM. Uh-huh. It is not compatible with TOPS, 
both old and current versions, nor is it compatible with any other 
spoolers. In short it isa real pain in the ass. The good thing Ican 
say for them, is that they're tech support people are pretty good, 
and more than willing to help with any problems. Two down. 

Another option was the QMS board that makes the Laserjet 
postscript compatible. It's expensive, (around $2500), and it's 
not Appletalk compatible. Three down. 

The Grappler LQ. One of you mentioned it here on the 
board. I'd heard about it before and they demo'ed it at 
MacWorld, but it's not shipping until March. However, after 
talking with the sales people and the tech support people at 
Orange Micro, this seems to solve the compatiblity issue. The 
Grappler LQ enables the Laserjet to mimic the Apple 
Imagewriter LQ. You use the Imagewriter LQ driver that Apple 
is shipping, and Orange Micro's serial to parallel converter. The 
Laserjet “smooths” out the 240 dpi of the LQ and prints it at 300 
dpi. Going by some sample copy I saw, this looks pretty good. 
Apparently this thing will make most popular parallel printers 
Work with the Mac. 

Asfor putting the Laserjet on the Appletalk network, I found 
the NetSerial by Shiva. This little sucker is expensive, (retails 
$399), but it works. It will put any serial device on the Appletalk 
network. Since the Grappler LQ is a serial device, the combina- 
tion of these two should work. 

From: mark.chally (Mark Chally) 

Subject: Mac to Hell(oops, PC) and back 

The successful transfer of files between a PC and a Mac 
requires two good terminal programs, a null modem cable (RS- 
232 with lines 2 and 3 crossed), and a little patience. I occasion- 
ally transfer files between my MacPlus and a “386 MesS-DOS 
machine... I use the. ImageWriter cable directly plugged into 
the СОМІ serial port of the PC compatible, ProComm on the PC 
(see me for that if you want), and MicroPhone on the Mac. It 
seems to work okay, at 19200 BPS... seems to me there’s some 
way to get the Mac to do 57600 too... maybe it’s Crosstalk that 
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does that. Also, there has recently surfaced a Mac version of the 
ARC program that’s so popular on the PC. In essence, ARC 
allows you to stuff a bunch of files together and compress them, 
in the same way that we're accustomed to using PackIt and 
StuffIt...I used ArcMac (again, see me if you want а copy) with 
relative success... the current version is BUGGY, and 
xArcMac.exe for the AT didn’t even work... but using the real 
ARC program did, though it complained about a garbage header, 
which was probably all the “extra” Mac stuff thrown into it... 
anyway, files successfully went both ways. 

From: jcom (Jim Comeau) 

Subject: Mac to PC 

I’ve used MacLink Plus with modem connections - slow-. I 
just got a 5.25 drive for my SE. You need to use Apple File 
Exchange to use the 5.25 drive. I was surprised when I found a 
very minimal set of translators were included. Oh yeah, now you 
can spend some money to buy each translator. But, if you have 
MacLink Plus you can use it to do local file transfers. The setup 
isto use AFE to do a binary transfer (no translation) between your 
Mac drive and the 5.25 drive. Then you use the rather complete 
set of translators that come with MacLink Plus to do the local 
translation. This setup works in either direction and it works 
FAST. If you have any large amounts of data I'd recommend it 
as the way to go. I haven't had any problems yet. The apple 5.25 
drive will write to an IBM HD disk at 360 KB but the IBM 
machine won't know what to do with it. Make sure you use DD 
disks. Hope this helps. 

From: billr (Bill Rausch) 

Subject: Mac to PC 

We use the TOPS network with 15 Macs and 3 PCs and 
everyone seems very happy. Excel reads and writes Lotus and 
Symphony files, and Word 3 reads and write PC Wordfiles right 
over the net without having to copy the files first. Of course, once 
you've read them in, you can Save As to put the resulting file 
(after your changes) either on the PC or your Mac and in any 
supported format. It is relatively fast, about like working off of 
local floppies, and relatively bullet-proof. We haven't had any 
kind of crash since TOPS 2.0 was installed. Also, we're trying out 
InBox from Symantec/Think and it is a great success. It is very 
easy to send someone a message and attach a file to it. For 
instance, you're on a Mac, run Excel, save the spreadsheet in 1- 
2-3 format, and then use InBox to send it to a PC user on the 
Appletalk network. He gets the message and saves the attached 
file on his disk. Then he uses 1-2-3 to read and manipulate it. 
Eventually he could reverse the process. (We're just now looking 
at PC Excel - it would make life even easier.) The nice thing about 
the E-mail approach is it doesn't require the simultaneous соор- 
егайоп of two people using TOPS (one has to publish and one has 
to mount a particular disk or directory). Anyway, we're very 
happy with both products and recommend them to anyone 
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From: jvsossian (James Von Schmacht) 
Subject: Re: Current Laserwriter version 
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Current version is 5.1 (for LaserWriter II’s) and reportedly 
has some of the spool problems fixed. Driver is available on 
MHDL. 

From: адай (Alan Dail) 

Subject: Scores Virus Got Me! 

I have aquired a virus on my system that seems to replicate 
itself on all of my applications. Itcreates files called Desktop and 
Score in the system folder. It causes MPW to not find the 
Worksheet file and may do other things. Has anyone come across 
this virus and does anyone know how to get rid of it? 

From: Inedry (Larry Nedry) 

Subject: Scores virus Effects 

This virus creates an invisible file call Scores. This is an 
ЕГЕУ resource which executes at boot time similar to an INIT 
resource. Another file is created called Desktop which is an INIT 
resource. The Scores virus also attaches itself to the Scrapbook 
File and Note Pad File. If they don't exist they are created. These 
files need to be deleted. Also the virus attaches itself into the 
System file and every application that you run. The best way to 
get rid of this virus is to throw away the System Folder and 
replace it with anew one. The Vaccine INIT by Don Brown of CE 
software will notify you when this virus trys to add CODE 
resources to your applications. You can also use the Aask INIT 
to prevent the INITs from being executed while you are trying to 
rid your disks of this virus. I am writing an application this 
weekend to hopefully terminate this virus from your system. 
When it is completed I will post info about it here and upload it 
to MouseHole Download. [This virus has been well reported in 
the press in MacWeek and Macintosh Today as the 'Scores' 
virus. It is dangerous so watch out. It was originally written to 
attack two internal programs at EDS in Texas and is said to be 
rampant in the Dallas area. Larry was quoted in the April 26th 
edition of MacWeek extensively about this virus and his Ferret 
program which detects it. -Ed] 

From: maxr (Max Rochlin) 

Subject: Scores Virus Symptoms 

The presence of the virus in the Macintosh memory does 
causes several symptoms, which have caused losses of data. 
These symptoms include difficulty running MacDraw, difficulty 
printing from any applications (especially MacDraw), difficulty 
using the “Set Startup" option, difficulty running Excel, corrup- 
tion of Excel files, and frequent crashes when starting applica- 
tions. This virus has existed since at last February, 1988, and may 
have been around as early as September, 1987. 

It is possible to determine if this virus has infected your 
Macintosh with the following procedure: 

1) Open the System Folder of the Macintosh and locate the 
“Note Pad File" and “Scrapbook File". 

2) Examine the icons used on these files and check that they 
resemble the small Macintoshes seen on the "System" and 
Finder" icons. If they do not, and instead resemble the standard 
Macintosh document icon (an upright piece of paper with the 
upper right corner folded forward), you are probably infected. 

3) To verify infection, execute ResEdit or some other utility 
which can see “invisible” files. Examine the System Folder. 

4) If the System Folder contains two invisible files named 
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“Desktop” and “Scores”, you are definitely infected. 

The virus transmits itself from Macintosh to Macintosh by 
invading a standard executable application file on a contami- 
nated Macintosh. When this contaminated application is copied 
to a "sterile" Macintosh, the virus attacks the new system by 
making these changes to the System Folder: 

e Three INIT resources are added to the “System” file. If the 
files “Мое Pad File" and “Scrapbook File" do not exist in the 
System Folder, they are created. The type and creator fields of 
the “Note Pad File" are changed from “ZSYS” and “MACS” to 
“INIT” and “7.5 У $”, respectively, and an INIT resource is added 
tothe file. The type and creator fields of the “Scrapbook File” are 
changed from “ZS YS” and “MACS” to “RDEV” and “ZS YS”, 
respectively, and an INIT resource is added to the file. 

• Two new invisible files are added to the system folder 
named "Desktop" and "Scores", each with an atpl, DATA and 
INIT resource. 

Note that, unlike the MacMag virus, no “nVIR” resources 
are used anywhere. The modified files, “Note Pad” and “Scrap- 
book", still appear to function normally with the Note Pad and 
Scrapbook Desk Accessories, and any existing contents of the 
file's Data Fork are not disturbed. 

As each application is attacked, the virus installs a new 
CODE resource into the application. The identification of this 
new resource is variable, depending upon the existing resources 
within the application. The virus looks for the first available 
CODE resource slot, then places the new resource one position 
above that. For example, HyperCard contains CODE resources 
0 through 20, leaving an ID of 21 as the first available resource 
ID. The virus placed the new CODE resource in the application 
as CODE ШЮ-22. 

The second step of the infection of the application is the 
modification of the CODE ID=0 resource of the application. The 
virus modifies the eleventh word of this resource, which is the 
start of the application's jump table. Where the application 
would normally jump to the CODE ID=1 segment, the virus 
modifies this pointer to refer to the new CODE resource that has 
just been installed. 

Note that the eleventh word has been changed from “0001” 
to “0016”, which points to the new CODE ID=22 resource (hex 
16 - decimal 22). Also note that during our examination of 
suspected applications, we found that at least one compiler - 
LightSpeed C, I think - normally places non-"0001" values in the 
eleventh word of the CODE ID=0 resource. To verify infection 
if the eleventh word is not “0001”, check to see that the tenth word 
is NOT “4EED” and that the eleventh word points to another 
CODE resource. If both of these are true, then the application is 
infected. 

The new CODE resource is a copy of the virus code, is of size 
1026, and is executed when the infected application is invoked. 
When the virus completes execution, it returns to the invoked 
application, which appears to proceed normally. The first sixteen 
words of the virus are: 

0000 0001 хххх ЗЕЗС 0001 АОҒ0 4EBA 002Е 2040 DOFC 0020 
АЗҒА FFEC 2009 2091 2040 ' 
The third word of the virus code is variable, and appears to 
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be based on the return address used when the execution of the 
virus is completed. The virus further modifies the code of the 
application in a manner which has not been fully deciphered. 

If your Macintosh is infected, the contaminated system files 
and applications must be completely removed from the Macin- 
tosh, and new ORIGINAL copies should be installed. When 
removing the virus from the Macintosh system files, you cannot 
just go in with ResEdit and delete the offensive INIT resources 
- this virus is apparently intelligent enough to recognize this 
attempt, and modifies it's resource identification and memory 
location when probed by resource utilities. ResEdit “thinks” that 
the virus resources have been deleted, but they have been 
renamed and will return when the Macintosh is restarted. The 
system must be sterilized by: 

1) Examine EVERY application (including any in the Sys- 
tem Folder, and on EVERY diskette you may have) you have 
with ResEdit, and check if а new CODE resource has been added 
and if the CODE ID=0 resource has been modified to refer to the 
new CODE. This is the most tedious part of the process, and will 
probably take quite a bit of time. 

2) Using ResEdit, open the infected System Folder and 
locate the “Desktop” file. Select the file and use the “Get Info” 
option on the “File” menu. When the file information window 
opens, turn off the “Invisible” bit, then close the window and save 
the file information. Do the same for the “Scores” file. 

3) Locate a sterile system diskette (preferably one of the 
"System Tools" diskettes from Apple), LOCK IT, and boot from 
it. 

4) Throw away the following files from the infected System 
Folder: "System", "Finder", “MultiFinder”, "Desktop", 
"Scores", "Scrapbook File", and “Мое Pad File". Once these 
files are in the Trash Can, EMPTY THE TRASH IMMEDI- 
ATELY! Note: this is the minimum required to remove the 
System portion of the virus - my personal preference is to delete 
the ENTIRE System Folder, not just the suspect files in it. 

5) Locate all of the applications which you listed in Step 1. 
Throw them away, and empty the Trash Can. 

6) Shut down the Macintosh, and turn the power off. Wait 
at least 30 seconds for memory to clear before rebooting again 
from the sterile diskette (this may not really be necessary, but 
better safe than sorry). 

7) Reinstall the Macintosh operating system from the Sys- 
tem Tools diskette to your Macintosh. 

8) Locate your original copies of the deleted applications 
software. Before reinstalling the applications, examine each one 
with ResEdit to be sure that it is sterile. If there is no problem, 
reinstall the application. 

А word of warning: 

The Vaccine CDEV which is currently appearing on bulletin 
boards is only marginally useful in fighting this virus - if your 
system is already infected when you install Vaccine, you will not 
get any warning from Vaccine that the virus exists. If you have 
Vaccine installed on a sterile system, and this virus is introduced 
atalater time, Vaccine will only warn you of the virus attack, but 
will not prevent infection. 

From: Inedry (Larry Nedry) 
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Subject:ScoresvirusUpdate 

The previous description of the Scores virus is not entirely 
accurate. There are also a ‘DATA’ resource -4000 and a ‘atpl’ 
resource 128 that need to be removed. If you attempt to remove 
the virus and are unsuccessful it will modify itself and the 
previous instructions will no longer work. 

From: wildman (Randy Saunders) 

Subject: MacroMaker bug?? 

I just downloaded the 1.0b9 version of MacroMaker from 
MHDL. It seems pretty neat, much better than Tempo, but it did 
something wierd. 

With MacroMaker in my System folder trying to print a 
MacDraw file causes an illegal instruction trap into MacsBug. 
Moving it out fixes the problem. I have: a) reloaded MacDraw 
1.9.6 from my master disk; b) reloaded the Imagewriter driver 
(ver 2.6 4/17) from its disk; c) Throughly checked for viruses and 
found no unwanted visitors in my system. I am running System 
4.2 and MultiFinder 1.0. I also have a number of other INITs, 
such as MFMenu, CPS Save Deletes, Front&Center, and of 
course Macsbug. Throwing out other guys does not fix the 
problem, although I did not try all the permutations. Is this a 
MacDraw 1.9.6 bug? (Other programs can print with Macro- 
Maker installed) Is this a MacroMaker bug? If so, what could it 
possibly be doing to bust Imagewriter printing from MacDraw 
only? 

From: jvsossian (James Von Schmacht) 

Subject: Re: MacroMaker bug?? 

I had the same problem printing in SuperPaint and Ver- 
saTerm. Nuked the puppy clean off my disk, and then reinstalled 
IW driver AND System. 

From: mikesteiner (Mike Steiner) 

Subject: STR Resource help 

I'm almost to embarrassed to ask this question, because I'm 
sure the answer is so simple, but I can't figure it out. How do you 
change a ‘STR ‘ resource from within a program? I can read the 
resource, place it in a editable field in a dialog, but I can't figure 
out how to write the change back to the resource file. 

From: rdclark (Richard Clark) 

Subject: Adding (and changing) resources 

Mike, Take a look at Scott Knaster's Book “How to Write 
Macintosh Software". However, if you don't have a copy handy, 
I'll summarize what you need to do: 

1) (This isn’t in the book). Take a look at the STR# format, 
and notice that it contains an integer (the number of strings) 
followed by a set of Pascal-format strings (strings with a length 
byte in position O). If you want to do anything that will affect the 
length of any of these strings, then you should take the STR# 
resource apart, make your changes and then put it back together. 

2) Now that you have a handle to your modified STR# 
resource, we can do the update. The simplest way is to call 

ChangedResource( theResource: ResourceHandle), 

then make a call to ResError() which should return noErr 
(namely, 0). You may then call 

WriteResource(theResource: Handle) 

to make the change *now*, or the Mac will do it for you when 
you close the resource file (such as when exiting the application.) 
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3) On the other hand, if you have a completely new resource, 
you'll have to do something different. Take a look at the 
folllowing code-like example: 


muHandle = МенНапа1е(100); /% 100 bytes... */ 
A Fill in the contents of myHandle here */ 


/* Now, we want to make this STR® resource #141, and 
completely replace anything that used to be there. 

So, we'll have to delete the old resource. 

NOTE: if somebody goofed, we may have 2 or more copies of 
STR" 141 already present, so get rid of all of them */ 


do ( 
quit = false; 
if (scratch = 0) 
quit » true; 
else 
scratch = GetResourceC'STR? ^, 141); 
if CHomeResFileCscratch) = CurResFile()) ( 
/* If the resource is in our current file, then delete it 
x/ 


RmveResource(scratch); /* Bye bye! */ 


else 


quit = true;  /* Exit if resource isn't in file 


x 
DisposHendleCscratch); 
) while (done = false); 
AddResource(myHandle, ‘STR®’, 141, °’); /* Add with no 
name */ 
Wr iteResource(myHandle); 


resource 
From: mikesteiner (Mike Steiner) 


Subject: Modifying STR resource 

About 10 minutes after I posted that message, I found out 
what I had to do, and it worked. After getting a handle to the 
resource (TheHandle), I then did the following: 

StrHdl := StringHandle (TheHandle); 

StrHdl^^ := Name 

(Name is the new string to go into the resource} 

ResourceChanged (TheHandle 2 

Of course, I took care of resource purge and hLocks, etc. 


before and after doing the stuff, and I did have the proper semi- 
colons in place in the listing. 

I need a bit more help. The method I stated in above works 
only if the replacement string is not longer than the original 
string. What do I need to do to be able to have a replacement 
string that is longer than the one it replaces in the resource? 

I found my problem. I needed the following call: 


SethandleSize (theHandle, sizeof (str255)); 
and that solved everything. 


From: the_cloud (Ken McLeod) 
Subject: Yet Another Resource Question 
I wrote a little CDEV that, among other things, wants to 
display the current System and Finder version numbers. As best 
Iknow how, you get the Finder version by doing a GetResource 
(or GetlResource) on the MACS ID-O string, taking the handle 
it returns and coercing it to be a handle to a string. Now the 
problem: it works just great everywhere EXCEPT when the 
Finder is open (which happens if the Control Panel is pulled down 
while in the Finder, or when running under MultiFinder). In that 
instance, GetResource refuses to give me any kind of access to 
the Finder (“File open with write permission" error). How can I 


/* Don’t clutter up memory */ 


/* You now have а new 
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get the Finder version number???? Incidentally, I get the System 
version number by calling SysEnvirons, so I don't have any open 
resource file problems there... Someone else has written CDEV 
called “Who's Who" that basically displays all the info from 
SysEnvirons. I tried it while in the Finder, and it gives me "Finder 
Version: Unknown,” so apparently he didn't figure it out either. 
Anyone see what I'm missing? 

From: rustyt (Rusty Tucker) 

Subject: Re: Yet Another Question 

Ifound one way to get at Finder resources, not quite painless 
though. This is a C frag but should be easy to convert to Pascal: 


OpenFinder() ( 
int err, sysVRef ; 
HParamBlockRec myParam; 
Str255 myName; 
err = GetVRefNumCSysMap, &sysVRef ); 
MemCopyC myName, “\pFinder’, 7 2; 
myParam.fileParam.ioCompletion = ØL; 
nyParam.f ilePerem.ioNemePtr = myNeme; 
myParam.fileParam. ioVRefNum = sysVRef ; 
myParam.ioParam.ioPermssn = fsRdPerm; 
myParam.ioParam.ioMisc = ØL; 
err = РВОрепЕҒС &myParam, 0 ); 
FileErrorDialog( err ); 
if С lerr ) ( 
ShowIntC "MpOpened the Finder ^", err ); 
err = PBClose( &myParam, Ø 2; 
жы. егг ); 


) 


The Mac will allow you to open the finder at this level with 
read-only permission. Natch you'll have to either copy the Finder 
RSRC fork into your own file then open it with the Resource 
manager, or parse the fork yourself and find the resource you 
want and make your own handle. 

There is another way that should work, but I can't find 
enough info on MF to verify it. Switcher used to set up a Global 
pointer to the APPL zones it set up at $282. The first 8 words in 
the deref'd table had Риз to the “base” of those APP's. What in 
the heck does that mean? I don’t know. Is it a pointer to the Heap 
Zone? If itis and MF maintains it you could just loop through that 
table and make SetZone(THz) calls followed by GetResource? 
Now that would be a lot easier than copying the darn Finder then 
doing a GetResource. So where are the other App’s when your 
under MF? Inquiring minds want to know. 

From: rickhyman (Richard Hyman) 

Subject: CDEVs 

Speaking of CDEVs (someone was), I created a small 
CDEV that included a EditText item in its DITL. This really 
screwed up the control panel; I took the edit item out and 
everything ran fine. Either the old RMaker is messing things up 
again or the control panel cannot handle all types of items 
possible in an appended DITL. I don’t know the source of the 
problem. Have other people found this to be the case? If so, is 
it documented anywhere?? 

From: wbigelow (Wendell Bigelow) 

Subject: ‘BNDL’ resources and the missing Appli- 
cation Icon 
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I've created ап application and added my own Application 
icon and icon for the files it will create. I do not see the fancy icon 
in the Finder when I view by icon, just the default application 
icon. I've read several places about removing the “Desktop” file 
and otherwise forcing FINDER to rebuild the desktop and go out 
amongst ye Applications and (re)built of BNDL resources. This 
Worked for a previous version of the application (and the files it 
had created) that uses the same icon image but has a different 
resource type (4 character doo-dah). I've deleted that particular 
BNDL resource and even managed to set the “bundle” bit in the 
GET INFO dialog in ResEdit for my application and forced 
desktop rebuild....ALAS...to no avail... 

From: the cloud (Ken McLeod) 

Subject: Finder BNDL checklist 

Did you: Make sure your application ICN# (and any ICN#s 
for documents created by your application) have corresponding 
FREF's? Make surethere'sacorresponding resource with ID=0 
for whatever your application's creator type is? Маке sure the 
BNDL's owner is the same as this creator type? Rebuild the 
desktop by holding down the Option and Command keys when 
quitting to the Finder? /The easiest way to get a new icon to 
appear is to use a new creator tag. Then the icon will be installed 
into the desktop file as soon as you use ResEdit to set the bundle 
bit. Otherwise, you have to get the desktop file to "forget" the 
previous icon for that creator tag, which is a pain to do. -Ed] 

From: allanc (Allan Clarke) 

Subject: palette manager blues 

Ihavean application which uses the palette manager. I keep 
aclut around and simply peel off copies (which are palettes) and 
attach them to the new graphics window(s). Unfortunately, my 
call to the palette manager does not seem to work on one out of 
about twenty-five Mac II systems (4.2). The call is... 

muPH= NewPalette(256,myCLUTmTolerant,@); 

if C!myPH) badnewsC); 

Ihad my beta site do some testing for me. Here is the strange 


part. He boots offa generic system and runs a copy of the software 
off his hard disk and it works. He quits. He can now relaunch my 
application any time and it does not have any clut error. 

When he restarts, though, back to square one. My applica- 
tion keeps ducking out with the Nil handle error. 

What is the difference between booting off a floppy and 
moving to the hard disk versus booting off the hard disk? I have 
already had him pull all the INITs out of the way. MACDTS told 
me there were no error codes (QDError) usefully returned to give 
me a hint as to why the Palette Manager could not perform the 
call. [You might check with last month' s issue on Palette Anima- 
tion to see if something is not being locked down properly. -Ed] 

From: Isr (Larry Rosenstein) 

Subject: Re: palette manager blues Comment: to 
#49 by allanc 

One thing that is different about the two situations you 
mention is that system patches are installed at boot time. It could 
be that the hard disk does not have the correct system on it, while 
the floppy does. 

From: matt (Matthew Snyder) 

Subject: system heap 
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The multitasker that I'm working on is written using a 
standard development kit, namely Mac C. Granted much of it is 
in assembly, I would still like to preserve the simplicity of using 
a standard compile-assemble-link-rmaker approach. 

As it exists now, it is an OPTIONAL multitasker. You 
install it by double-clicking on its icon. It is loaded like an 
application into the application heap. It then does some ex- 
tremely unmentionable things to move the barrier between the 
heaps and thereby sort of pull the covers up. It becomes part of 
the system heap and at the same time expands it. 

Note: This is being used in an experimental and research- 
oriented environment, and there is really no intention of ever 
marketing it. As a result, I am not overly concerned with main- 
taining compatibility with future machines or future system 
software. 

However, I am not happy with the complexity and the 
underhandedness of the whole thing. 

The multitasker was originally ported from a different 
machine, where it also ran in the background, but where it used 
a native stay-resident facility. I was convinced that there must be 
such a native facility for the Mac. 

I found that using resedit to mark the code resource as 
system- heap-destined would indeed cause the stuff to be loaded 
into the system heap, and I was trying to find out if I could turn 
this discovery into a stay-resident algorithm. 

In response to your responses, I have another question. You 
say that the system heap can be expanded if you do it right, but 
that it can't be expanded while an application is running. What 
is happening while the loader is placing the next application into 
memory? If I specify that I want my code resources to be placed 
in the system heap when I get loaded, will the heap expand to 
accomadate me or not??? 

From: rdclark (Richard Clark) 

Subject: Re: system heap 

If youare using System 4.0 or later, youcanresize the system 
heap at boot time using an INIT. The system recognizes when an 
INIT requests a block in the system heap and expands the heap 
if needed. (However, this isn't a nice thing to do as the 
Application heap shrinks. But, you already know that, right?) 

And, I just remembered, there's another thing you can do! 
Instead of placing your code in the System Heap (requiring 
System 4.0++ and an INIT, you can place your code at the TOP 
of memory, up where only globals, the stack, and the ROM jump 
tables dare to tread. Look at “How To Write Macintosh Soft- 
ware" for an example of this. (Some RAM disks use this area, 
which is guaranteed to stick around between launches and which 
can be modified by an application. But, once you allocate the 
memory, it's unlikely you can ever deallocate it since somebody 
else may request a block below you and you don't dare move 
them. I doubt that this will create a problem for you.) This 
program wouldn't happen to be MultiMac 2.0, would it? «grin» 

From: alpha (Jean Thomas) 

Subject: XCMDS 

Question: If you create a window with an xcmd/xfncs in 
Hypercard, how do you handle events in your window without 


733 


calling GetNextEvent? Whenever I do, events іп my window аге 
handled correctly but HyperCard is frozen until xcmd. If I don't 
call GetNextEvent, HyperCard is still active but I can't handle 
my window events at all. Any ideas? It makes sense, ie freezing 
Hypercard if you call GetNextEvent yourself, but how else could 
you tell when you are in your window? I suppose FrontWindow 
might do it alone, but I'll see. Any help appreciated. Has anyone 
else on this board written any Hypercard xcmds? 

From: rickhyman (Richard Hyman) 

Subject: Re: XCMDS 

HyperCard was designed using its own event manager and 
memory manager; I'd like to know why because that really limits 
the kind of XCMDs you can build. You can handle events 
yourself by setting up a dialog for all of your user interface 
requirements. This points to the fact that XCMDs must be modal; 
ie. anything your XCMD does must be completed, memory 
completely cleaned up, etc. by the time you complete your 
XCMD. Yes, you can use FrontWindow to find where you are, 
but there are situations where you can't be sure the user hasn't 
brought up the tool window, pattern window or message win- 
dow. GetNextEvent doesn't work if you are using HyperCard 
buttons and text fields because HC does its own event managing. 
You can get away with creating dialog boxes and the dialog 
manager calls because that should be totally self contained in a 
single XCMD. It seems to be a good idea to flush events before 
handing control back to HC. If you are using HC for all of your 
user interface requirements, you may be able to break your code 
up into a number of smaller XCMDs. After spending 4 months 
on a stack and *then* running into these kinds of problems, I'm 
pretty frustrated with HyperCard. Not only does it need to 
conform to Mac interfaces from a user perspective, it needs to 
conform to interface and ToolBox standards as well. Unless it is 
cleaned up quite a bit, it will never be what Atkinson intended it 
to be. 

From: alpha (Jean Thomas) 

Subject: Re: XCMDS 

Iagree with you about the limitations of XCmds and external 
programming in Hypercard. Unfortunately, if you create a win- 
dow with scroll bars etc, there is no way, at least I can see, to 
update your window without calling GetNextEventin your code. 
SelectWindow is not enough because I don't know if HyperCard 
even knows when you have clicked on someone else's window. 
Perhaps you can send a series of idle messages to Hypercard. I 
don'tknow. Thanks for your help. I don't really think HyperCard 
was written for the traditional programmer. 

From: rickhyman (Richard Hyman) 

Subject: Re: XCMDS 

The only way I found of updating various portions of my 
card, or specific windows was to use a series of transparent 
buttons on top of the appropriate areas. I experimented with 
mouseUp and mouseDown handlers to call the appropriate 
XCMD. This worked reasonably well for a list for which I used 
List Manager. If you are using multiple overlapping windows on 
a single card, then it would be difficult. If you have a single 
window with scroll bars, et al, then the use of several transparent 
buttons might work. But then, ... the several XCMDs would all, 
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by necessity point to the same data structure for your window. © 
So, you'd like to keep this structure in memory between XCMD 
calls, which HC could clobber any time ... and now we seem to 
be going in circles. Yes, HyperCard needs some work yet to be 
easily extended by programmers. [ВШ Atkinson demonstrated 
the next version of Hypercard at the Developer conference and 
indicated that a lot of internal bug fixes and changes have 
resulted in Hypercard both being much faster as well as the 
interface with dialogs being much cleaner. Some of these prob- 
lems with XCMD' s will go away with the next release, which 
should be out shortly. -Ed] 

From: Isr (Larry Rosenstein) 

Subject: Re: Setting Startup from an app 

Probably the safest thing to do is to write an application that 
launches another application based on some string resource. 
Then you should do Set Startup and choose the Finder (instead of 
MultiFinder) and choose to launch this application at start up. 

By default, the string resource can specify MultiFinder, and 
then your machine will start up with MultiFinder. Later on, 
however, an application can change the string resource and have 
it start up with itself. You can make your startup program smart 
enough that it will default to MultiFinder if there is nothing else 
to launch. You might also make it do a sublaunch of the non- 
MultiFinder application (see Tech Note 4126), and then launch 
MultiFinder when that application quits (or give the user a choice 
of another application). 

From: Isr (Larry Rosenstein) 

Subject: Tear Off Menus 

I just read the Tear Off Menu article in the April MacTutor. 
It looked very complete and useful. I have only 1 minor 
complaint. On p. 32 the authors talk about the ToolScratch low 
memory variable, and the conflict between the Menu Manager 
and Lightspeed C. Inside Macintosh says that ToolScratch is not 
guaranteed to be preserved across calls to the Toolbox; it is 
designed to be scratch space for the Toolbox use. So the conflict 
is not the ROMs fault, it is LSC’s. 

From: wbigelow (Wendell Bigelow) 

Subject: MacPaint/MacDraw ‘PICT’ files 

HELP! I’m in the middle of implementing a nifty user 
interface. Unfortunately, I needed to create graphical objects I'll 
be displaying, in MacDraw and then save them as “РІСТ” files. 
My hope was to somehow generate MPW compatible “РІСТ” 
resource statements and manipulate these graphical objects as 
resources to be displayed in my nifty window design. I've got 
everything ready but I CAN'T FIGURE OUT HOW TO GET 
THESE MACDRAW GENERATED ‘PICT’s into the resource 
fork of the file I' m saving them in, soIcan DeRez them in MPW. 

From: the cloud (Ken McLeod) 

Subject: PICT moving 

When all else fails, the Scrapbook desk accessory is a tried 
and true method of moving PICTS around. Try copying your 
MacDraw PICT and pasting it into the Scrapbook. Then go into 
ResEdit and open up the file you want to save the PICT into. 
Create a new PICT (select New, choose PICT from the scrolling 
list, and then select New again). Bring up the Scrapbook and 
select Paste! -k 
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Ғгот: апаус (Апау Соһеп) 

Subject: Hyperproblems 

The discussions on the problems of building XCMDs and 
XCMDs over on the programming board have given some 
insight to problems in plain Hypertalking. Ever try to get the 
polygon tool to draw a polygon via “click at” or maybe try to get 
the freehand curve tool to drag to. Well, the poloygon tool ignores 
all click at commands (even though Hyper goes back to the 
browse command when told to) and the Curve tool draws only 
from one point to the next then closes the figure for each Drag. 
Hypercard only does things in a single minded serial manner. It 
can’t do anything else until the called job is done then control is 
given back. The best approach then is to keep any functions to be 
called extremely brief in their execution time. 

BTW using card buttons (set the LOC property) one can 
actually do some slick animations. A hard to find fact that is easy 
to deduce; just as in all things in the Mac environment fonts, picts 
and icon resources can reside in files as well as apps. If you are 
producing a Hypercard stack which MUST have a certain font 
and size or requires customized icons use resedit and paste these 
resources into the stack. If the stuff is already there it just 
duplicates them while the stack is opened by a Hypercard which 
already has them. If you do this then your stack can be used by 
any Hypercard. 

From: rsobel (Richard Sobel) 

Subject: 68010 PROCESSOR 

Can anyone out there give the pros or cons for switching the 
68000 chip with a 68010. ie. speed, extra instructions, etc 

From: frank (Frank Henriquez) 

Subject: 68010 

The 68010 is pin and instruction compatible with the 68000. 
The main difference is that the 68010 can support virtual memory 
and memory management chips better than the 68000. The added 
instructions are mainly to deal with these new features. Some of 
the looping instructions have been modified, so that short loops 
are executed from the instruction cache, without having to go out 
and fetch it each time throught the loop. This speeds things up for 
very small loops. Some other instructions may have been tight- 
ened up a bit too. As to replacing the 68000 with a 68010: 
Motorola claims up to a 30% speed improvement. It’s probably 
not much more than 10% for average operations. Since replacing 
the 68000 on a Mac means some *considerable* unsoldering 
(ever try to unsolder a 64 pin IC from a four layer PC board with 
really teeny traces?...) I don’t think it's worth doing. If the 68000 
were in a socket, then it might be worth the premium price of the 
“010. 
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From: the cloud (Кеп McLeod) 

Subject: TearOffPalettes Error 

The TearOffPalettes source, as published in the April 1988 
issue of MacTutor, contains an error which doesn't exist in the 
fully functional "Source Code Disk #31” version. Of course, 
there weren't апу errors introduced into the Palette WDEF.c file, 
since it wasn’t even printed. In the TearOffMDEF.c file (the 
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menu definition), the function ChooseItem() includes the follow- 
ing line: 


if! CtearOffMGlobals)->itemHilited) ( 


hiliteItem = CtearOffMGlobals)-»currentItem; /* wrong! */ 
CtearOf fMGlobals)-»itemHilited = true; ) 
This is NOT correct, and should instead be: 
ifC!CtearOffMGlobals)-»itemHilited) ( 
/* right! */ 


saveltem = (teerOffMGlobals)— currentItem; 
(teerOffMGlobals)-»itemHilited = true; ) 


as itis in the Source Code Disk version, else the hiliting gets 
screwed up real good. 

From: Isr (Larry Rosenstein) 

Subject: MF Background Bug 

I just got the May MacTutor and on page 12 is a question 
about a possible MultiFinder bug. This bug is described in Tech 
Note #177. The letter had the bug almost right. It doesn't depend 
on the application having no windows. The bug shows up if: 

(1) an application has the background bit set and calls 
WaitNextEvent with a sleep value > 50 and 

(2) the application becomes the frontmost application be- 
cause another application quits. 

The maximum sleep value is dependent on the machine: 
larger values could be used on a Mac Plus and Mac SE. Also, 
condition 2 can be satisfied by running and then closing a DA. 
The bug is fixed in the upcoming 6.0 system. You сап tell if the 
fix is in place by using the SysEnvirons call and checking the 
System version. (The Tech Note gives the wrong number for the 
check; the version should be greater than $0430.) My Time- 
Keeper program does this check and when running under System 
6.0 will sleep for up to 1 minute under MF. (BTW, it also utilizes 
the Sound Manager on the Plus/SE under 6.0.) 

From: davidw (David Whiteman) 

Subject: Technote/Claris Question 

Does anyone know whether the old Apple Technotes 
describing the file formats of MacWrite, MacPaint and 
MacDraw documents are accurate for the recent versions of the 
applications released by Claris? 

From: rick (Rick Boarman) 

Subject: Re: Technote/Claris Question 

As far as I know the MacWrite 5.0 file format is the same as 
4.6. MacDraw II has a completely different structure than v1.9. 
You can still save a drawing as a standard PICT though. 

From: davidw (David Whiteman) 

Subject: Re: Technote/Claris Question 

Greetings, Claris finally returned my phone call: Basically 
with MacPaint and MacDraw, the two new versions have an 
entirely different document format, but if you create a document 
following the guidelines as described in the Apple technotes the 
new programs can still read it. With Mac Write 5.0 there are some 
subtle changes in the document format. Claris will not make the 
specifications for the newer versions public, nor post them, but 
if you write, and have a good reason for asking for them and sign 
an NDA, they will furnish it. [50 much for document format 
standards! Neither the new MacWrite or Word 3.01 formats are 
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now easily accessable to developers. -Ed] 

From: davidw (David Whiteman) 

Subject: Mac ІІ ADB problems 

Some time ago I posted asking for information about prob- 
lems with the ADB port on the Mac II. 

After talking to some hardware experts I discovered the 
following: Apparently if you disconnnect anything from the 
ADB port while the Mac is powered on you may briefly short 
some pins. This causes a fuse to blow on the Mac II motherboard. 
Which would eventually mean that you would have to buy a new 
motherboard as the fuse is soldered in. The whole point is that if 
youare going to connector disconnect the mouse or the keyboard 
power off the Mac first. 

From: rdclark (Richard Clark) 

Subject: Re: Mac Il ADB problems 

There's another reason to power down before changing 
ADB devices. Each ADB device has a microprocessor in it, and 
this mpu receives a “reset” command from the Mac at powerup. 
If youconnect another ADB device in after the machine has been 
powered up (or disconnect and reconnect an existing device), the 
new device will not be reset properly. 

From: wbigelow (Wendell Bigelow) 

Subject: Missing Application icon 

I've created an application and added my own Application 
icon and icon for the files it will create. I do not see the fancy icon 
in the Finder when I view by icon, just the default application 
icon. I've read several places about removing the “Deskktop” 
file and otherwise forcing FINDER to rebuild the desktop and go 
out amongst ye Applications and re-build the BNDL resources. 
This worked for a previous version of the application (and the 
files it had created) that uses the same icon image but has a 
different resource type (4 character doo-dah). I've deleted that 
particular BNDL resource and even managed to set the "bundle" 
bit in the GET INFO dialog in ResEdit for my application and 
forced desktop rebuild....ALAS...to no avail... [The best solution 
isto usea series of similar creator tags and to change the creator 
tag with each new icon you wish to use with a version of the 
program. Then when the bundle bit is set, the Finder will install 
the new icon with the new creator tag. However, if the tag has 
been previously used, you have to make the Desktop file "forget" 
the old iconassociated with that creator tag. This is very difficult. 
Itismucheasier to teach the Desktop about a new creator tag and 
icon than to make it forget the icon associated with the old tag. 
-Ed] 

From: the cloud (Ken McLeod) 

Subject: Finder BNDL checklist 

Did you: Make sure your application ICN# (and any ICN#s 
for documents created by your application) have corresponding 
FREF's? 

Make sure there's a corresponding resource with ID=0 for 
whatever your application's creator type is? Make sure the 
BNDL's owner is the same as this creator type? Rebuild the 
desktop by holding down the Option and Command keys when 
quitting to the Finder? [Be careful of this step; sometimes things 
get messed up, especially if you have a very full hard disk. -Ed] 

From: davidf (David Fandel) 
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Subject: List Manager/MacApp problem 

Are there any MacApp experts out there? I am working on 
a list manager object that is a descendent of DialogItem. I have 
gotten the modal dialog box routines to work correctly. (ie. the 
scrollbars work, items are selected, etc.) But whenIcall the same 
routines from a modeless dialog routine the scrollbars do not 
show up initially. If the list is selected the paging regions and the 
thumb appear and move, but they can’t be selected. The up and 
down arrows never show up. And if another window hides them 
they are not updated when the other window is moved. My call 
to this routine is based on a slightly modified DemoDialogs 
modeless dialog call. My code is as follows: | 


NewCaDialogView); 
FailNilCaDialogView); 
aDialogView. ILMDialogView( 2; 
(override - cells IDialogView) 
aWindow := aDialogView.MakeOwnW indow (FALSE); 
(creates window} 
IF eWindow € NIL then 
begin 
aWindow.fFreeOnClosing := TRUE; 
aWindow.fOpenInitiallly := FALSE; 
SimpleStagger( ); 
aListView := aDialogView.Def ineSimpleList(4, 
18, TRUE, FALSE, theStr ing); 


(this is the call that places the List listed in theString 
into item number 4 of the Dialog Box іп an 18 pixel high cell. 
The TRUE means а rectangle is drewn around the list end the 
FALSE means the list is NOT alphabetized) 


eWindow.open; 
end; 


The DefineSimpleList procedure runs new and FailNil on 
TSimpleList (a DialogItem descendent) and then calls the ISim- 
pleList initialization routine which basically makes the list and 
attaches itto the DialogPtr after coercing itto a WindowPtr. Any 
clues on why the scrollbars go out to lunch when it is modeless? 
Have I forgotten an important call? 

From: dcamp (David Camp, El Paso, TX) 

Subject: cdev's 

Hi! Can somebody show me the link command required to 
link the sample cdev in inside Mac V? Or the link command for 
the ApplFont cdev in MacTutor V3#10? This is for MPW Pascal 
by the way... I can't seem to nail it down and several people on 
GEniecan'teither. [All you need is a code resource. Do you need 
a special link command to get the MPW linker to create code 
resources? -Ed] 

From: the cloud (Ken McLeod) 

Subject: StartSound problem 

I recently used HeapShow to check out a program I'm 
writing, and discovered to my chagrin that a handle wasn't 
getting unlocked, causing heap fragmentation. I tracked the 
problem down to this bit of code, which involves calling 
StartSound asynchronously: 


HLockChandleCTheSound)); 
TheSound* ^ .FFSound.count := fixratio€1, TheSound**.rate); 
WITH TheSound** 00 

BEGIN 
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StartSound(ëFFSound, WaveLen, pointer(Syn)); 
END; 
HUn lock ChandleCTheSound)); 


When (Syn) is -1, the sound is produced synchronously; 
however, when (Syn) is 0 and the sound is being produced 
asynchronously, the handle never gets unlocked. In fact, my calls 
to HLock and HUnlock the handle appear to have no effect... I 
removed them, and the handle was STILL locked on exit from the 
routine. Does anyone know if there’s something I’m doing 
wrong here, or if there’s a problem with StartSound? I seem to 
recall some thread about StartSound here before... І should 
mention that my handle to the sound is declared as a global 
variable... is that a factor? 

From: Isr (Larry Rosenstein) 

Subject: Re: StartSound problem 

There is a general problem with your code as written, which 
could manifest itself as a locked handle (but I don’t know for 
sure). The problem is that StartSound expects a pointer to the 
sound data. Locking the handleis the right thing to do, except that 
it has to be locked for the duration of the sound. If you call 
StartSOund synchronously, then there is no problem. If you call 
it asynchronously, then you can’t unlock the handle until the 
sound finishes. The correct thing to do is to use a completion 
routine to detect when the sound is finished, set a flag, and unlock 
the handle when your program sees the flag set. Youcan’t unlock 
the handle in the completion routine, because it runs at interrupt 
level, and could have interrupted the Memory Manager. (If you 
use a global flag, you also have to be careful to setup A5 correctly, 
and watch out for MultiFinder.) I don't know if this could cause 
the handle to stay locked, but it could certainly cause problems 
playing out the sound if you unlock the handle while the sound 
is playing. 

From: the cloud (Ken McLeod) 

Subject: More StartSound... 

Well, I tried setting a flag after I called StartSound asynchro- 
nously (passing nil for a completion routine), and putting a few 
lines of code in my main event loop to unlock the handle if 
SoundDone was true and the flag was set. It should have 
worked...but didn’t. Then I got an inspiration, and thought of 
StopSound; so... this works: 


if CunlockMeFlag and SoundDone) then 
begin 
StopSound; 
HUnlockChandleCmySoundHd122; 
unlockMeFlag := FALSE; 


end; 


But without the StopSound call, the handle remains locked! 
If we get past SoundDone there should be no need to call 
StopSound; this is truly bizarre. StopSound “executes the 
sound's completion routine" as well as cancelling any pending 
calls (there aren't any), so perhaps it won'tallow the handle to be 
unlocked if a sound is played asynch until some sort of comple- 
tion routine is called? Idunno... anyway, StopSound did the trick. 

From: jimr (Jim Reekes) 

Subject: Re: More StartSound... 
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The glue code in MPW for StopSound unlocks the handle 
created by StartSound. StopSound glue checks for the handle and 
will unlock it for you. The meaning behind all of this is to call 
StopSound before ExitToShell. )]> reekes «[( 

From: tony (Tony Fashoro, San Jose, CA) | 

Subject: Calling Code Resources 

Help, I want to write a standalone code resource using LS 
Pascal. I need to know how to call the code resource form within 
an application. I beleive I have to use the resource manager to 
load and lock the resource and then do something to the handle 
returned by the resource manager. What is that something ? 

From: think (Richard Slegel, Bedford, MA) 

Subject: Re: Calling Code Resources 


Calling the code resource is pretty straightforward: 
procedure CallCodeCargi, arg2,...,argN, codeH); 
INLINE $205F, $2050, $4E00; 


The first N arguments are the arguments that your code 
resource's MAIN routine expects, and “содеН” is a handle to 
your code resource. 

NOTE: Before calling the above procedure, you should 
either lock the code resource (you can set its locked bit in the 
resource attributes, if you want) or make provision for it to lock 
itself. If the code resource moves while it's executing, you're 
dead... —Rich Siegel, THINK Technologies 

From: polaris (Jamal Hannan) 

Subject: Resource Problems 

Hello. I need a little help here... I am writing a program in 
Pascal & one of the procedures in it needs to get hex data from a 
resource of type DATA into an array, where each byte can be 
utilized individualy... I can't seem to get my program to work.. 
here it is: 

PROGRAM Arry; 
TYPE 

туАггау = ARRAY[1..10] OF INTEGER; 

myArrayPtr = “myArray; 

myArrayHd! = “myArrayPtr; 

VAR 

filename : STR255; 

theResID : INTEGER; 


theRefNum : INTEGER; 
enArrayHd! : myArrayHd!; 


PROCEDURE QuickAndDirty; 
BEGIN 
theRefNum := OpenResFile(filename); 


anÁrragHdl := myArrayHdlCHaendleCGetResource( ‘DATA’, 
theResID))); 
END; ( QuickAndDirty ) 


BEGIN 
filename :- 'Rscs'; 
theResID :- 1000: 
QuickAndDirty; 


END. 


Anyone know whats wrong? Can you show me aroutine that 
would work? 


From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: Re: Resource Problems 

Is it possible that GetResource(‘DATA’, theID) is conflict- 
ing with a DATA resource in another open resource file (like the 
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compiler, or the System?) Perhaps using Се(1Кезошсе instead 
of GetResource might help... (just a guess, nothing more). 

From: isr (Larry Rosenstein, Cupertino, CA) 

Subject: Re: Resource Problems 

Itis possible to get a resource conflict. In your application, 
however, your application resource file, or any resource file that 
you open will be searched first. Only if it is not found there will 
other opened resource files be searched. (Also, under MultiFin- 
der, other applications won't be visible at all.) GetlResource 
might solve the problem. Also, you can see if this is in fact the 
problem by calling HomeResFile on the resource you get and see 
if it coming out of the resource file you expect. 

From: polaris 

Subject: resource 

Help... It was written in Lightspeed Pascal & I had the linker 
automatically include the resource file so I didn't need to call 
GetResource Anyway...thatcode WOULDNT work and simply 
by looking at it probaly wouldn't tell anyone much.... anyway, I 
wrote some compleatly different code and it worked... here it is: 


PROGRAM Open; (Jemal Hannan ... 5/18/88) 
VAR 


thing : PACKED ARRAYL1..200] OF INTEGER; 
(setup addressable array block) 
resType : STR255; 
resID : INTEGER; 
resHandle : Handle; 
resPtr, thingPtr : Ptr; 
blockSize : Size; 
BEGIN 
гезТуре := ‘DATA’; 
resID := 1000. 
resHandle := GetResource(resType, resID); 
LoadResource(resHand le); 
resPtr := resHandle^; 
(get resource pointer from handle} 
thingPtr := @thing; 
(get pointer to point to array block) 
blockSize := GetHendleSize(CresHendle); 
(get size of data block) 
BlockMoveCresPtr, thingPtr, blockSize); 
(nove res data into аггау space) 


(load up the resource...) 


END. 


The previous code was really something mostly written by 
someone on EchoMac (sort of a FIDO or OPUS email system for 
Macs)... it really didn't work for me so I wrote my own. I think 
the problem with the last section of code was some Ptr or Handle 
type coersion... some pointers ended up pointing to the wrong 
memory blocks... NOW whatIneedisa bitof code that will save 
an ARRAY into a RESOURCE.. exactly the opposite of the 
above... but Iam having alot of trouble... can anyone help me with 
that? 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: Saving an array to a resource 

Well, if what you want to do is save an array intact, and 
restore the exact same array to the exact same state, you can do 
the following: (* DANGER! DANGER! DANGER! This code 
has not been tested! *) 


procedure DumpArray(theArray: arraytype; theRes: resType; 
resNum: integer); 
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var 
scratchHand: Handle; 
thisResFile: integer; 
done : boolean; 


begin 
(If an old copy of the resource exists, remove it } 
thisResFile := CurResFile; 


(Should be done in main program, since you want the resource 
number of your application. } 
done := false; 
repeat 
scratchHand := GetResource(theRes, resNum); 
if CscratchHand O nil) then 
if CHomeResFileCscratchhand) € CthisResFile)) then 
done := true; 
else 
( We have one or more copies of this same resource in our 
file, so delete it Cand dispose of the body) } 
Re leaseResource(scratchHand); 
until done; 


( Now, we can create а handle to hold the array ) 
scratchHand := Newhandle(sizeof Carraytype)); 

( Copy the data from the array to the resource } 
BlockMove(@theArray, scratchHand*, sizeof Carraytype)); 

( Now, put the resource into your resource file } 
AddResource(scratchHand, theRes, resNum, ‘’); 
ChangedResource(scratchHandle); 

( Checks to be sure there’s disk space ) 
WriteResource(scratchHand); (Save it } 
end; 


From: rguerra (Rich Guerra) 

Subject: Multifinder questions 

I have a couple of questions regarding programming for 
Multifinder. 

1) I’m trying to write an application that will be able to 
sublaunch another application while running under MF, but does 
not itself close. Control is transferred to the newly launched 
application which is now in the foremost layer. I’ve tried the code 
in Tech Note 126 (Sublaunching) and set the two high bits of 
LaunchFlags as specified in an addendum to the Multifinder 
developer’s documentation. However, the application gets 
launched and my application quits. Has anyone tried this code 
and made it work? | | 

2) How does one determine how much memory is a) allo- 
cated for an application under MultiFinder and b) how do you 
determine the amount of the allocated space that is actually used. 
(1.е., something similar to the Finder About box that gives all this 
information graphically) Any suggestions would e appreciated. 

From: thotpolc (Bill Evans, Irvine, CA) 

Subject: Complaint Time 

Okay, fellas it's Complaint Department time. 

Complaint One: 

In the MacsBug documentation there is mention of some- 
thing called the "current heap zone" under the HX, HC, and HD 
commands, and by implication also the HS and HT commands. 
This is completely different from the "current heap zone" as 
discussed in Inside Macintosh and determined by the TheZone 
global variable (at $118). It's quite good that they're different; 
it gives one acertain debugging flexibility. But (at leastin MPW 
1.0) the MacsBug documentation doesn't say that they're differ- 
ent. So when I forgot to change TheZone back to the application 
heap, I didn't suspect it at first because the HC command quite 
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innocently told me that my current heap was still the application 
heap. So beware. Check $118 if you want to know whether your 
program is working in the right heap zone. 

Complaint Two: 

The Inside Macintosh documentation for Secs2Date (p. II- 
380) says that it returns a pointer to a date/time record. Wrong. 
You set up the pointer in А0 to a date/time record for which you 
have allocated the space, and Secs2Date will fill thatrecord. One 
would expect IM to be more clear on this point, since in most 
cases it is scrupulously careful in questions of this sort. 

Complaint Three: 

I'm sure most people who are interested know this, but I'll 
state it for the record. The Inside Macintosh documentation for 
GetHandleSize (p. П-33) says “іп case of an error, GetHandle- 
Size returns 0”. Wrong. In case of an error, GetHandleSize 
returns the (less-than-zero) error codes listed at the bottom of the 
page. Butthose result codes aren't quite right, either. They show 
noErr as meaning "No error". Actually, in case of no error, you 
get the (greater than or equal to zero) size. 

Complaint Four: 

This last one isn't about documentation; it's about a botch in 
design details of QuickDraw. When you use the Memory 
Manager to get and resize handles and pointers and the like, you 
have adequate warning when an operation fails because of lack 
of memory. You can go off and pursue an alternative course of 
action without bombing the system. Not so when QuickDraw 
causes you to run out of memory. The best you can do is make the 
current heap be something whose grow zone function at least 
warns the user that he's run out of memory — but even this 
function, returning "failure" to QuickDraw, can't prevent Quick- 
Draw from bombing "25". If we're encouraged (and rightly so) 
to be fastidious about checking for no more memory with 
Memory Management traps, why can't we be given the same 
opportunity with QuickDraw? Granted, a region may be fouled 
up beyond repair if QuickDraw runs out of main memory, but 
can't it just then set it to contain nothing and let us decide what 
todo from there? [T' m convinced no one at Apple understands the 
proper way to do memory management on the Mac or they would 
have told us by now. It is the number one "black magic" art of 
Macintosh Programming. Scott Knaster' s books made the best 
effort at the subject, but that only scratched the surface of what 
is needed. -Ed] 


From: cmkrni (Егіс Slosser) 

Subject: recover from a HD crash 

The following program is meant to read the last block of 
SCSI drive 0 and copy it to the 2nd block. The purpose is to 
overwrite a corrupted Master Directory Block so that Disk First 
Aid will be able to repair the disk. (As outlined in Tech Note 
#134, p.11) This is my first attempt at using PB driver calls, so 
I've messed something up. I get an ‘Illegal Err’ during the 
PBRead. The PC is somewhere in 'Create' (according to 
Macsbug). Anyone саге to comment (once you stop laughing) 
on this? 


PROGRAM FixDisk; 
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USES ($LOAD PesSymDump) Memtypes, Quickdraw, OSIntf, ToolIntf, 
PeckIntf ; 


CONST 

SCSI_Zero_dQRefNum = -33; ( IM IV-215 and IM II-191 ) 
VAR 

theQHdr : QHdrPtr; ( IM 11-373 ) 

eQElem : QElemPtr; ( IM IV-181 ) 

thePB : PeremBlockRec; 


theBuffer: ARRAY [1..128] OF INTEGER; ( total size - 512 ) 
SizeOfVol: LONGINT; 


err : OSErr; 

BEGIN 
theQHdr := GetDrvQHdr; 
eQElem :- theQHdr^ .qHead; 


debugger ; 
we are going to babysit this code ) 
( бо through queue, looking for SCSI device ZERO ) 
WHILE а0Е Теп «€ theQHdr^.qTail DO 
(we do this to get the ioVRefNum) 
IF CaQElem* .DrvQElem.dQRefnum <> SCSI. Zero. düRef Num) 
THEN 
eQElem :- aQElem^.DrvQElenm.qL ink; 
IF CaQElem* .DrvQElem.dQRefnum = 
SCSI Zero -dQRefNum) THEN 
BEGIN 
( It’s an 80MB drive, so we have to combine 2 
fields for the size ) 
SizeofVol :- BSLC aQElem^.DrvQElem.dQDrvSz2, 16 ) 
+ aQElem* .DrvQElem.dQDrvSz; 
WITH thePB DO 


BEGIN 
ioCompletion := NIL; 
ioVRefNum := aQElem^.DrvQElem.dQDr ive; 
ioRefNum := SCSI_Zero_dQRefNum; 


ioBuffer := @theBuffer; 
ioReqCount := 512; 
ioPosMode := fsFromStart; 
ioPosOffset := (SizeofVol -1)*5 12; 
END; ( of filling in the param block ) 
err := PBRead( 8thePB, FALSE ); 
( we die inside this call. Why?) 
IF Cerr<>noERR) THEN 
debugger ; 
... the code would go on here to mimic the above, 
only writing ) 
7 
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From: pepnerd (Peter Kramer) 

Subject: menus 

I'm just a beginner at programming the mac. I'm trying to 
set up menus using the code in "Using the Macintosh Toolbox 
With C" by Takatsuka et. al. I'm not sure how to call InitGraf() 
in the situation where I have not set up any windows, only menus. 
In my development system the example (Aztec C) the call to 
InitGraf() uses the argument &thePort. However I cannot find 
where thePort is defined. Its quite distressing to double click on 
an application icon and get nothing but a bomb! 

From: егісііт (Егіс Lim, Flushing, NY) 

Subject: Re: menus 

I'm notfamiliar with Aztec because I'm using MPW C 2.0.2 
and I think the variable thePort is defined in the *Quickdraw.h" 
header or include file. 

From: think 

SubJect: Re: menus 

It’s notimportant to know where thePortis defined; all that's 
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important is that you pass the correct series of initializations in 
order to get your application started: 


( 
InitGrafC&thePor t); 
InitFonts(); 
InitWindows( ); 
InitMenus(); 
ТЕП О 


InitDialogs(NIL); ) 


Typically, thePort is defined as an extern GrafPtr in 
Quickdraw.h (in LightspeedC) or in the appropriate header for 
other C compilers. —Rich Siegel, THINK Technologies 

[The variable thePort is one of those mysterious Quickdraw 
global variables that no one ever talks about once you are 
convinced the proper call works correctly. The first few issues of 
MacTutor, over three years ago, addressed this subject in depth, 
explaining how the Quickdraw Globals are stored relative to A5 
and how they work. The Mac system is responsible for the 
Quickdraw Globals maintenance. Refer to Volume 1 of The Best 
of MacTutor for more information. -Ed] 

Subject: cdev's and System 6.0 

Practically all the public domain/shareware cdevs I used 
with no problem under System 4.2/Control Panel 3.2 appear to 
break under System 6.0/СР 3.3. Usually it's “Тһе Control Panel 
cannot get enough memory" (with almost 2 megs free?!), but 
other alerts have popped up as well. One of the "broken" cdevs 
includes the Apple “Sample” cdev from IM V, which I compiled 
myself. Hmmmm.... I think the problem may be that these cdev’s 
do not have a ‘sysz’ resource. Am I right? 

Well, after looking more closely, I discovered the reason 
why various cdev's were breaking under System 6.0: they check 
for the presence of certain packages in the System file (usually 
PACK 7 or PACK 4) that no longer exist! (except in the ROM). 
Even Apple's Sample cdev in IM V does this (although there's 
a brief disclaimer that you "really should" check for the packages 
in ROM). Ouch. Then there's the MultiFinder test. Most sample 
source code I've seen (actually, ALL) checks for MultiFinder's 
presence by testing to see whether the WaitNextEvent trap is 
implemented. Now, in System 6.0, it's implemented ALL THE 
TIME, whether you're in MF or not. So if application X assumes 
it's running under MultiFinder when it isn't, well, look out. 

Question: how do you detect MultiFinder's presence or 
absence under 6.0? [Answer: Your not supposed to саге if 
MulitFinder is there or not; only check for the various services 
you expect. -Ed] 

From: tomh (Tom Herbst, Ithaca, NY) 

Subject: Palette Manager п LSP 

I am having a great deal of difficulty adding the necessary 
interface file to use the Palette Manager with LightS peed Pascal. 
I manually entered the appropriate data structures, inlines, etc. 
gleaned from Inside Mac V, the MacTutor articles, and the 
Programmer’s Online Companion (all consistent), but the 
SetPalette calls crash even MacsBug with bus errors. Is there a 
copy of the necessary code along with a simple (i.e. create a 
palette, a NewCWindow, and draw a rectangle) program ex- 
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ample out there somewhere? My PaletteMgr and example pro- 
gram compile ok, but run very inconsistently, sometimes draw- 
ing things in the default (startup) palette and more frequently 
crashing the whole shebang. 

From: ericlim (Eric Lim, Flushing, NY) 

Subject: Modeless Dialog/List Manager 

HELP! HELP !! Doesanyone know of a technique on using 
the List Manager Package іп a Userltem inside a Modeless 
Dialog? I don't want to create the window and controls on my 
own, I want to use IsDialogEvent and DialogSelect. Any sugges- 
tionsonhow Ісап dothis? So far, I’m getting asystem error when 
IuseLNEW with rView set to the rectangle of the Userltem. I got 
the Modeless Dialog to work on a regular dialog with a UserItem. 
I also got the List Manager to work on a regular window that I 
created. But it just bombs when I use Modeless Dialog with the 
List Manager Package. I would appreciate any help or sugges- 
tions I could get. Thanks a lot! /Forget the Dialog Manager and 
just use the list manager into a window. -Ed] 


From: tompink (Tom Pinkerton, lowa City, IA) 

Subject: Ending DA drvrCti routine 

For a while now, I’ve been using an ending to the дгугСИ 
desk accessory routine that was supplied with my MDS develop- 
ment package. That ending, rather than simply returning, calls 
the low-level Device Manager routine IODone (pointed to by the 
JIODone global variable) before returning. I've been blindly 
keeping this in all my DA sources without really knowing its 
purpose. I assume that who ever wrote the sample DA for the 
MDS development system knew what heor she were doing when 
they added this call. АП I can figure is that the call somehow 
clears the IO Request sent to the DA from the driver IO Queue so 
that other devices won't receive the request (since they needn't 
bother with it, I guess). Does anyone know anything about this? 
a 
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From: bruceh (Bruce Henderson, Canoga Park, 
CA) Sat, 2 Jul 88 15:22:46 EDT Comment: further 
comments 


Subject: MAC and MC88000 


The Motorola 88000 is pretty much THE processor of the 
future. After going to the Motorola seminars and studying the 
docs on it, I feel that the power offered here is something that 
hopefully Apple won't pass up. 

I think the optimum design would be to use to 88100s. One 
for graphics only and the other for everything else. If both of the 
processor modules used 2 88200 CMMU’s on the instruction 
side of the path (32K) then it would be possible to store 1 segment 
in the CMMU at all times. [ more on why this is importiant later 
] Other system memory could be configured to operate in burst 
mode. So as the 88100 needed another segment, it could read it 
ina ^BURST". [for those of you not so hardware intensive hacks 
burst mode allows the CPU to fetch a large amount of data from 
memory at the highest possible rate]. The 2 processor sets could 
be connected via the 88000 p bus so that the interrupts could 
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occur 1 cycle. Yes, this idea doesn't have а lot of refinement, but 
I have been doing a great deal of thinking about ways that a 88K 
Mac could exist, achitecture and such. And I have decided to 
appoint myself the independent Mac88000 evangelist. The 
power is just too great to pass up. 

Wait, you say. The 88000 isn't software compatible with 
the 68000! Ah, this is where the ROM/Toolbox guys at Apple 
will have to earn thier pay. The trick is to make the Mac88000 
source code compatable with the rest of the Mac line. If every 
last one of the Mac ROM calls can be implemented on the 
Mac88000, then the trick is just to allow MPW to generate 88000 
code as well as 68000 code. So to make an Mac88000 version 
of a current peice of software would only requore a recompile 
with the {+88000} flag set. This may seem like too much to ask 
for, but the truth of the matter is is that if Apple were to go ahead 
with this now, while the hardware hacks were making the box, 
the toolbox critters could be already creating the code for this 
things ROMS, thanks to the Tektronix 88000 MacII board. So 
really, the ROM development team doesn’t have to waituntil the 
hardware guys had somthing that works. So I know that all of 
you LightSpeed guys are howling out there. I think that Apple 
Should make sure that the major compiler writers are seeded as 
soon as they have anything that works! 

Well, there is a lot more to my Ideas, If anyone is really 
interested they can contact me, or just wait for the nexttime I feel 
like having an 88000 revival meeting..... 

From: frank (Frank Henriquez, La, CA) 

Comment: to 481 (bruceh), further comments 

Subject: Re: MAC and MC88000 

Yeah, the 88000 is real swell, but it's Motorola's first 
attempt at a RISC machine, and it does have it's nasties: Forget 
about writing code in assembly language. Not only is the instruc- 
tion set (and addressing mode) extremely limited (well, it's a 
RISC machine) you have to keep track of azillion little CPU 
states and modes and whatever. So, we've settled on writing in 
a HLL. Fine. To really squeeze out the maximum performance 
out of the beast, the compiler has to be smart enough to know 
when and how to generate code that executes in parallel. I don't 
think we'll be seeing LightSpeed C (or any other compiler) for 
the 88000 *that is any good* selling for peanuts...or a nice pile 
of C notes. The hardware is a dog. Too many things going on at 
once. The bus interface to the “rest of the world" (memory, 
peripherals) is a multiplexed 32 bit bus with some unfriendly bus 
signals (WHAT! по Read/Write signal? sheesh) Yeah, it'll take 
a while to get used to the beast. 

I'd rather see a 68030 (or 68040) running at 88000 speeds 
with some intelligent memory controllers (to eliminate or mini- 
тіге the need for an obscene # of wait states) Motorola has 
promised such a beast (the 68040) at some point, and it would be 
compatible with 68000 and 68020 code. 

Of course, you could emulate the 68000 with an ECL 
version of the 88000, but I don't want to buy a liquid nitrogen 
cooling system for such a machine... 

The 88000 is a great machine, and one notable feature is that 
the microcode can be customized. I'd love to see an 88000 based 
graphics controller for the Mac. Quickdraw (or Display Post- 
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script, or whatever) would really scream. 

I wouldn't mind a 50 MHZ 68040 Mac with 1G or ram and 
a terabyte optical HD and a 2000 x 2000 pixel 48 bit color display 
with an 88000 for the graphics. Who needs a Cray, anyway? 


From: rusty (Mr. Rusty Hodge, Orange, CA) 

Subject: Re: MAC and MC88000 

The 88000 is more comparable to the AMD 29000 than to 
the 68000 family. If you treat the 88000 like a microcoded HLL 
engine, I think it will perform nicely. Ithink that Apple will end 
up with even a more custome machine than the Mac when (if) 
they go to the 88000. 

If the 88000 is microcoded properly; it will be able to give 
the performance to the kinds of tasks that the Mac OS need the 
most performance in. However Apple is going to have to create 
the microcode to turm the 88000 into a usable HLL engine. 

Maybe the 88000 will become the basis for a true Hardware- 
Quickdraw? Or maybe the basis for an PostScript HLL engine? 
It isn't that hard to do. 
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From: rkk (Russell Kadota, Huntington Beach, CA) 

Subject: menus & resedit 

I'm just getting started in Mac programming, and I've run 
across something that one of you more experienced folks might 
be able to explain. I was writing a simple program to just put up 
a menu bar and handle DAs. I created a resource file with the 
appropriate MENU resources using Resedit 1.1b3. After much 
debugging anguish, I found that the MENU resources didn't have 
the resource numbers stored in them. I had changed them to 128, 
129, etc. using the ‘Get Info’ command in Resedit. Is this a 
problem with Resedit, or with the MENU TMPL, or am I doing 
something wrong? I'm usingLightspeedC, on a vanilla mac plus. 
Thanks in advance. 


From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: Re: menus & resedit 

The function GetMenu() takes one argument: the resource 
ID of the MENU resource you've created. This is the same 
number you've set by using ResEdit's “Get Info" command 
(128,129, etc.”). You don't say what problem you experienced, 
but if you're using LightspeedC, the MENU resources should be 
stored іп a file named <PROJECTNAME>.rsrc, where <PRO- 
JECTNAME?» is the name of your Project file. The individual 
resources don’t have the resource ID numbers stored *in* them, 
but the toolbox routines you'll call to get and make use of the 
menus (or any other resource) don't care; just pass them the ID 
number, and assuming a resource of type MENU with that ID 
exists, the function will return a handle to it! You can then pass 
that handle to other functions that need a MenuHandle as an 
argument... If you can't solve the problem, explain what you're 
trying to do in more detail and hopefully we can help... 


From: rkk (Russell Kadota, Huntington Beach, CA) 
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Hmm, I guess I wasn't very clear in my description. I created 
the resource file (named appropriately), and set the resource ids 
of the menu resources to 128, 129, and 130 (apple, file, and edit). 
The program finds the resources just fine, and draws the menus 
and all the items correctly. But when I try to select something, 
MenuSelectreturnsa 0 for the menu id (although the item number 
is correct). 

What made me think that the menu id (same as resource id?) 
was stored with the resource was that I used Fedit to inspect some 
other resource files and found a number which matched the 
resource number 14 bytes before the first character of the first 
item, in each case. So I used Fedit to put a similar number in my 
resource file, and presto, everything works. So, I guess the 
problem is “solved”, but not too elegantly. 


From: thecloud (Ken Mcleod, La Habra, CA) 


MenuSelect returns a long... the hi word should contain the 
menu ID, and the lo word contains the number of the selected 


menu item. You would normally do something like this: 
DoMenuEventCMenuSelectCEvent .where)); /* MenuSelect result */ 


void DoMenuEvent(menuChoice 2 
long menuChoice; 
( 
short whichMenu; 
short whichItem; 
whichMenu = menuChoice ›› 16; 
whichItem = menuChoice & OxFFFF; 


/* HiWordCmenuChoice). */ 
/* LoWordCmenuChoice). 
*/ 


/* use switchCwhichMenu) to go to other functions for 
handling each menu, passing them CwhichItem). */ 


“7 > 


Now, assuming you're doing this, and still getting 0 in 
(whichMenu), possibly the MENU resource wasn't written 
properly when it was created or changed. I looked at some 
MENU resources with ResEdit's “Open General", and the first 
word is indeed the resource ID (0080 for a menu with 
ID=128,and so forth). You shouldn't have to use Fedit, though, 
or do any kind of bit twiddling with the resource to make this 
happen! You might want to try using a different version of 
ResEdit (I’ve been using 1.241 with no problems; 1.242 is the 
latest I've heard about), or compiling your menus with RMaker, 
to see if you can isolate your copy of ResEdit as the problem. 

From: rkk (Russell Kadota, Huntington Beach, CA) 

Thanks for the help. It turns out that it was indeed my copy 
of ResEdit. I picked up a newer version (1.2d(something)) and 
everything works OK. Thanks again! 
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From: rick 

(Rick Boarman, Claris Corporation) 

Subject: MacDraw Il PICT2 Spec 

The file format spec for MacDraw II is now available!! To 
get a copy of it all you need to do is write a letter letting us know 
why you want it and what you're planning. We'll approve all 
reasonable requests. Send the letter to: 

Claris 

440 Clyde 

Mountain View, CA 94043 

Attn: MacDrawII Product Manager 

From: emmayche 

(Mark Hartman, Fullerton, CA) 

Subject: System 6.0.1 

Well, the unofficial distribution is finally here - and seems 
to be OK. None of the color problems we had with 6.0, and fixes 
to some we had in 4..2. I'llleteverybody know if we run into any 
problems. 

ГІ be making the rounds of the user group meetings in 
Orange County for redistribution purposes (and promotional 
purposes - Photon Paint is now at your local dealer). 

Get System 6.02, NOT 6.01! 

From: rdclark (Richard Clark, Tustin, CA) 

Is NOT thelast word in Systems. (Justread your AppleLink, 
Mr. Developer) Apple just warned all of the Certified Develop- 
ers NOT to ship 6.0.1 with their products, butto get System 6.0.2, 
which is due out shortly (this week?)/Richard is right. System 
6.01 is buggy. The OFFICIAL release of system 6 is 6.02. -Ed] 

From: rguerra (Rich Guerra, lowa City, IA) 

Subject: MultiFinder Magic 

It seems the humorous About box in MultiFinder 6.0 was 
hidden a bit better than in the first release. If left alone for about 
1 hour, the ‘About MultiFinder’ dialog will flash a funny mes- 
sage. But for those of you who don’t want to spend an hour 
staring at your screens, you might try this: Using a file editing 
program like FEdit, SUM, or even ResEdit search for the hex 
string 034BCO and change to 0000CO. There are two occurrences 
of this string, so change both. If you're using ResEdit, open thé 
CODE resource 1 (“Маш”) and use the Hex search function. 
This applies to MultiFinder in System Release 6.0. I don’t know 
if this will work on the new 6.01 or higher. After this patch, the 
about dialog will alternate between the standard text and the 
funny message. Remember, DO THIS ON A СОРҮ!!!! 

From: miket 

(Michael Twitty, Los Angeles, CA) 

Subject: Apple Price Increases 

There seems to be something I don’t understand about this 
price increase. If their justification is the current high RAM 
prices, why did they raise the price of their monitors? Trust me, 
I looked inside...no RAM! [The price increases across the board 
are considerable. Since the Macintosh was already overpriced to 
begin with, this just makes it worse. We welcome predictions on 
the market effect of this move. -Ed.] 

From: rusty (Mr. Rusty Hodge, Orange, CA) 

Apple Corporate is getting fat, lazy, and inefficient. Look at 
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the System 6.0 fiasco. Why did they FedEx 6.0.1 to developers 
telling them that it was still buggy and to wait for 6.0.2? Apple 
is gloating in their success. They are convinced that they can do 
no wrong. They spend their money making their headquarters 
fun to work in for their employees. They keep the employee 
refrigerators stocked with beer and wine coolers. 

It seems that most of the talent is gone from Apple. A few 
bright, hard working people are making all the progress for an 
otherwise stale company. Face it. These price increases are 
unfounded. They are just another creative/strange marketing 
idea: If they raise the price, more people will buy the machines 
fearing that the price will increase again! /That only works for 
cars and other necessities. -Ed] 

From: emmayche 

(Mark Hartman, Fullerton, CA) 

Subject: Playing snd 2 resources 

Here's a message to MACDTS from one of the other 
programmers here. Any ideas, anyone? 

I've been through the IM-V chapter on the Sound Manager 
with a fine-toothed comb, and my supposedly simple quest to 
have my Mac II play a sound that’s been digitized and is in a ‘snd 
° type 2 resource has me stumped. 

Here's some code (Think-C) that doesn't work: 


include | *SoundMgr .h^ 
8def ine nil OL 


nainC) 


Handle effect; 
SndChannelPtr channel; 
SndCommand sound; 
effect = GetResourceC'snd ', 10000); 

if Ceffect == nil) 

penicC^can^t GetResource”); 

HLockCef fect); 
channel = nil; 

if CSndNewChannel(&channel, 5, initSRate22k, nil) != 

noErr ) 
panic(“can’t SndNewChannel^); 
if (SndPlayCchannel, effect, TRUE) != noErr) 
panic(*can’t SndP lay”); 

sound.cmd = noteCmd; 

sound.param! = 1000: 

sound.param2 = 0хҒҒ000037:; 

if (SndDoCommand(channel, &sound, TRUE) != noErr) 

panic(“can’t SndDoCommand”); 
if (SndDisposeChannel(Cchannel, FALSE) != noErr) 
panic(^can^t SndDisposeChannel^); 


HUnlockCeffect?; 
ReleaseResourceCeffect); 


) 

Now, my interpretation of IM-V is that I have the sound 
digitized in a snd-2 resource, and that I load it with SndPlay and 
then I play a note to get it to come out at whatever frequency and 
duration. However, it never gets that far. I always get a "can't 
SndPlay" output, with the error code of “badFormat” returned. 
I'vesingle-stepped through the SndPlay trap, and what it “looks” 

like happens is that SndPlay looks at the ‘snd’ resource type and 
won't play anything but snd-1 resources. So, what's the story? 
How do I play a digitized sound, if I'm not supposed to use 
SndPlay? 

I have a bunch of other Sound Manager questions that ГИ 
defer for the moment. If anyone would like to volunteer as a 
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Sound Manager expert, I'd appreciate the help. If anyone can 
send me some code that works with the Sound Manager, I'd 
appreciate looking at that as well. At this point I'm frustrated 
enough by all of the things that I *have* tried that I'll appreciate 
*anything*. 

From: mkg (Marsh Gosnell, Montclair, NJ) 

The following code plays both type 1 and type 2 snd 
resources. 


theHendle = GetResourceC'snd ', id); 
LoadResource( theHandle); 

HNoPurge( theHandle); 

SndPlay(@, theHandle, false); 


It works fine on my Mac II and Mac + both running 6.0 

From: retzes 

(Steven Retzlaff, La Mesa, CA) 

I had a similar question in the programming/pascal topic, 
One problem seems to be the earlier system release: a bug in 
format-2 SndPlay was fixed in System 6.0. 

From: wilicox (Dave Willcox, Chicago, IL) 

Subject: multifinder and clipboard 

Тат having aclipboard programming problem under Multi- 
finder. Various programs (4th dimension, LabView, etc) allow 
for the creation of “external procedures” in Pascal, etc. I have 
written a procedure to put TEXT onto the clipboard so that it 
could be pasted into other programs under Multifinder. First, this 
is necessary because programs like 4D can have the user put a 
given field on the clipboard, but can not combine fields, etc into 
asingle clipboard entity. The procedure is a simple two line 
program: ZeroScrap, and PutScrap. However, the following 
happens under Multifinder (5.0, 6.0, take your pick). First, my 
program works as evidenced by a “Show Clipboard” while still 
in4D. However, after a context switch, the clipboard in, lets say, 
WriteNow is empty. If сору something іп WriteNow, it shows 
up in the 4D clipboard. Strangely, І сап copy my stuff onto the 
ScrapBook under Multifinder, and then do acontext switch into 
WriteNow, and copy it again out of the Scrapbook. However, 
this is a two step process for the user, which should be simpler. 

Гат convinced that this has to do with MultiFinder’s use of 
the Scrap. Each application has its own scrap, which must be 
converted when a suspend event is received. However, 4D does 
not do this because it has no private scrap, so it thinks that it 
doesn’t need to do a conversion. I have tried to change the 
MultiFinder flags in the SIZE resource, but 4D currently says that 
it does not accept suspend/resume events anyway. 

From: kevink (Kevin Killion, Chicago, IL) 

Don't know if it’s related, but I'm wrestling with a nasty 
scrap problem also. In my app, if more than about 10K of 
material (TEXT, PICT or whatever) is placed on the scrap, there 
will be a crash when the program is Quit. It can be as simple as 
copying a largish item from the Scrapbook and then Quitting. As 
you said, it's a simple matter of ZeroScrap, PutScrap so it's hard 
to see what could go wrong. The crash only happens on a Mac 
II, and only if the scrap has more than 10K or so. According to 
TMON, the crash occurs at $AD92, which TMON labels as 
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GetNewPalette. 

From: retzes 

(Steven Retzlaff, La Mesa, CA) 

Subject: Writing a Serial Driver 

I am interested in writing a specialized Serial Driver to get 
more direct control over interrupts and the 8530-SCC registers. 
What I am wondering is how to deactivate and/or redirect certain 
system resources that interfere with serial communications such 
as: 1: The Existing ROM Serial Driver which the call to 
RAMSDOpen presumably closes. 2: The Disk-Driver feature 
which automatically transfers characters from the serial port to 
the system Serial-DRVR while interrupts are disabled during 
disk access(—IM Volume 2: About the Disk Driver). I would 
appreciate any comments or suggestions, or any others regarding 
writing a serial driver. 

From: rdclark (Richard Clark, Tustin, CA) 

Unless you REALLY need that much control, writing your 
own serial driver isn’t such a hot idea, since when Apple changes 
the HW, you'll probably break. [See the December and January 
1988 issues of MacTutor for an example of a printing driver and 
be prepared for a lot of work. -Ed] 

From: dsa (Dave Stine, Saugus, CA) 

Are you sure that you want to invest the time & heartache 
necessary in writing a Macintosh driver? Mac device drivers, 
especially those intended torun under MultiFinder are not for the 
faint of heart. If you wish to supplant the serial driver that is 
called when your application performs a PBOpen() on .Ain, what 
you might consider doing is putting your DCtlEntry in the 
UnitTable where the DCtlEntries for the old .Ain and .AOut are. 
This way, all the Mac ROM calls to the supplied serial driver will 
now call your driver. As for how the .Sony driver grabs interrupts 
intended for the serial driver and makes the characters appear in 
the serial driver’s buffers when the .Sony driver re-enables 
interrupts, I would suggest that you disassemble the .Sony driver 
and the serial driver. The interrupt conflict in the Sony driver 
with the serial driver would most cleanly be solved by the use of 
DMA in reading the disks, but I guess Apple hasn't invented 
DMA yet. 
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Because this is the international edition, we thought we' 
originally planned to translate the entire article into Japanese. 
However, since MacTutor doesn't have the Kanji fonts for the 
LaserWriter, it was decided just to pretend that the column was 
translated into Japanese and back to English again (like the rest 
of the magazine was!). 

From: wayne (Wayne Correla, Cupertino, CA) 

Subject: Mac lix 

The Mac //x isa 16 Mhz. 68030 with a 68882 math coproces- 
sor. Thenew floppy driveand SWIM chip (Super Woz Integrated 
Machine) allows the reading and writing of Mac formatted 400k/ 
800k/1.44mb disks, 800k Apple ProDos, 720k/1.44mb IBM 
formatted disks. The logic board is available as an upgrade for a 
little over $2000 and the drive and SWIM chip upgrade is 
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available for $599. The 68030 has built-in memory manage- 
ment, soa68851 PMMU is notrequired for A/UX operation. The 
base machine also comes with 4 Meg RAM on the motherboard, 
and room for 4 more. The ROMS are now mounted on an Apple 
ROM-SIMM board that plugs into a SIMM socket where the old 
28 pin DIP ROMS used to be. Also, If you are only interested in 
the 1.44 drive, you can just buy the drive kit which installs in any 
Mac II. Ihave had one of these on my desk for about two months, 
and the //х is VERY compatible with Mac applications! 

From: wildman (Randy Saunders, Upland, CA) 

Subject: Getting Turned Down for developership 

Yes, it does seem the rule is *Will you be selling something 
at ComputerLand in 24 months"? Nothing against Computer- 
Land, but I have always chaffed at this particularly dumb rule of 
Apple's. If you do contract programming as a consulting 
engineer it seems they think developership is above you. It 
doesn't matter if you have contracts with the US Government 
(the world's biggest computer buyer) Apple doesn't think you 
are serious. 

If youaren't trying to eek out your existence selling software 
to “the rest of us" then they will do everything within their power 
to stand in your way. Never mind that the people I consult with 
buy the brand of computer I say the software I wrote for them runs 
on, period, no other factors come into the matter. I can only guess 
itis a hold over from the Jobs days when Apple saw itself making 
the next great electric toaster and thought that every home would 
have one. With the new and increased price of a Mac II, this 
camper just doesn't see the sense in it. 

My comment is, no matter what stupid things Apple does, if 
you just stand by and they'll do something stupider soon. Thanx 
to good people in the Mac community (the folks on MouseHole 
in particular) support from Apple is just not the kind of thing 
you've gotto have. Its easier to live without them than put up with 
their bulloney. 

[Of all the questions on the Apple Developer Question form, 
the only one that they seem to pay attention to is “Will your 
product be on the market within the next 24 months?” . If you 
answer no to that, you' ll become a “Mailing List Class" devel- 
oper, which means you'll get tech notes and newsletters, but 
nothing much more. - Rusty] 

[I personally agree with your sentiments. Apple has always 
ignored the thousands of developers working in industry in 
vertical markets because they were not developing the next MS 
Word. This attitude has always bugged me. -Ed] 

From: billd (Bill Dugan, Huntington Beach, CA 

Subject: nVIR virus returns 

We made the acquaintance of the nVIR virus recently at UC 
Irvine's school newspaper. We've got a 290MB file server 
running AppleShare, with about 7 SE's with hard drives and 4 
with floppies accessing it. Shared applications. Shared viruses. 
Now the virus is everywhere you look. I ‘vaccinated’ all the 
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startup volumes with the May MacTutor аз а reference guide. 
But does anybody know if nVIR is really a problem? Has 
anybody lost any data? (Don’t quote some yokel from MacTutor 
or something who insists every new MacWrite release causes 
problems with his MacPaint 1.0.) We got the “Don't Panic" 
Macintalk message a couple times (after signing off NetTrek, so 
it happens) but that's the only effect. [The nVIR virus does not 
appear to be fatal to anything but it is nasty and pervasive. Get 
rid of it, and I do mean all of it, at once. -Ed] 

From: rusty (Mr. Rusty Hodge, Orange, CA) 

The biggest problem with nVIR is that it doesn't seem to be 
too compatible with 6.0.2. We were getting semi-random 
crashes until we realized we had it and eliminated it. 

[Just when we thought that the virus epidemic was over, we 
were hit. Of course, this happened about 4 days before a major 
project deadline. Moral: always check for viruses, and back up 
your entire hard disk weekly - Rusty] 

From: billd (Bill Dugan, Huntington Beach, CA) 

АП I’ve done so far is patch the System files, with an INIT 
32 that contains a $4E75, and then deleted all the nVIR resources 
and replaced them with empty ones, ID 0 through 7. Haven't 
messed with applications yet at all. Interferon did detect nVIR on 
one hard drive (Virus RX did NOT!) and I found out by surprise 
that it eradicates the virus by deleting the applications! Whoops. 
[All applications must be "cleansed" or your system will be re- 
infected. I said it was nasty. -Ed] 

From: adept (Roy Lovejoy, Silicon Valley) 

Subject: Print Record Flelds moved. 

How nice of them to do this. If your print routines are not 
working, this may be why.. 

1) The number of copies set in PrJobDialog is not stored in 
the iCopies field of the prJob field of the print handle. (that would 
be too easy) It is really stored in iRowBytes field of the prXInfo 
field. 

2) Likewise the percentage of enlargement/reduction can be 
found in the iBandH field of the prXInfo. 

3) as per previous “Landscape” question, you can determine 
portrait/landscape by looking at the rPaper field of the print 
handle. If rPaper.right > rPaper.left then you have Landscape 
mode on. (theoretically, until Apple changes that too!) 

The only reason I can figure why these changes have taken 
place (1 & 2)is what I gleaned from a conversation with an Apple 
project manager in the Printer group. He basically said that they 
don't want developers mucking with the Print Handle them- 
selves, only using the routines given. (if routines would be able 
to setalloftheattributes that the PrJob & PrStyle Dialogs do, then 
I could understand this.. But until that day....) Hopes this helps 
someone.. p.s. the fields mentioned in 1 & 2 are read/write, i.e. 
you can change them. 

From: retzes (Steven Retzlaff, La Mesa, CA) 

Subject: LSC 3.0 math-library problem 
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I was trying to use LSC to compile a Mandelbrot-graphics 
program and ran into the following problem: link error: _ fabs 
-log _sqrt . This was with 68020 and 68881 code generation 
enabled, ERRORCHECK and МС68881 defined, math.h 
included, and the math881 library added to the project. the 
program usage was something like: 

fxr = fabs(xder) ; 

dist = log(x2+ty*sqr t(x2+y2)/sart(xder*xder+yder*yder) ; 

All the variables are locally defined as double. The program 
refused to compile unless I changed the function names to. log, 
_sqrt, and. fabs. Even when it linked, the fabs routine intermit- 
tently caused a Bus-Error-Exception and according to the LSC 
Debugger, failed to assign a value to the Left-Hand-Side variable 
fxr from fabs. The rest of the 68881 inline-operations (+,-,* /) 
seem to work ok, but the math-functions don’t link properly, and 
fabs doesn’t work( I had to use a if <0 statement to emulate it). 

From: robert (Rob Anthony, Chicago, IL) 

Subject: C “pretty printer” 

A rather non-technical question: a friend of mine is looking 
for а “С pretty printer, preferably with varying fonts”. I don’t 
usually program in C, suggestions? 

From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: Re: C “pretty printer” 

I have “PrettyPrint 2.0”, by Andrew Shebanow... you can 
select font and size, as well as a number of other options (italicize 
comments, etc.). It allows you to pretty-print C, Pascal or 
assembly source. 

From: chenette (Philip Chenette, LA, CA) 

Subject: Opening ICONS 

A question— I’m playing around with a copy of MiniEdit, 
the program which is developed in Stephen Chernikoff' s MacIn- 
tosh Revealed. I'm trying to learn Mac programming from this. 
When I quit the program, I can't open any other Icons on the 
desktop. They select just fine, but double clicking to open just 
doesn't work. Rebooting solves the problem. Any thoughts on 
what's going on here? 


From: thecloud (Ken Mcleod, La Habra, CA) 

MiniEdit does something it's not supposed to do: it changes 
the system event mask. Look for a call to 
SetEventMask(theMask), where *'theMask" is (I think) keyUp- 
Mask... comment out this line, and your double-click problems 
will go away. This was a bad blunder, considering MiniEdit is 
supposed to be the quintessential “example program"! 


From: chenette (Philip Chenette, L A, CA) 

THANKS! Itried this question on Compuserve a few weeks 
ago—Nary a response! [It is not entirely MiniEdit's fault. Apple 
changed something in the system file a while back and several 
older applications started showing this problem. -Ed] 
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